cascade-ai 0.78.0 → 0.79.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.79.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,694 @@ async function discoverMcpTools(servers) {
   return results;
 }
 
+// src/browser/lease.ts
+var LEASE_DEADLOCK_CEILING_MS = 3e5;
+var QUEUE_WAIT_MS = 18e4;
+var MAX_QUEUED = 8;
+var ACTION_HANDOFF_MS = 2e3;
+var ACTION_HANDOFF_POLL_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;
+  isRevoked;
+  onChange;
+  constructor(options = {}) {
+    this.isRevoked = options.isRevoked ?? (() => false);
+    this.onChange = options.onChange ?? (() => {
+    });
+  }
+  get holderActor() {
+    return this.actor;
+  }
+  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 === 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();
+  }
+  /** 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.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. */
+  beginAction() {
+    if (this.action) return null;
+    const token = /* @__PURE__ */ Symbol("browser-action");
+    this.action = token;
+    return token;
+  }
+  /** Release the slot, but only for the action that took it. */
+  endAction(token) {
+    if (this.action !== token) return false;
+    this.action = null;
+    return true;
+  }
+  /**
+   * Wait, briefly, for an outgoing action to unwind.
+   *
+   * 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 waited out rather than refused — but bounded, because a
+   * wedged action must not pin the queue.
+   */
+  async awaitActionSlot() {
+    for (let waited = 0; waited < ACTION_HANDOFF_MS; waited += ACTION_HANDOFF_POLL_MS) {
+      if (!this.action) return true;
+      await new Promise((r) => setTimeout(r, ACTION_HANDOFF_POLL_MS));
+    }
+    return this.action === null;
+  }
+  /**
+   * 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 ACTION_TIMEOUT_MS = 3e4;
+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();
+  /** 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 Set();
+  /**
+   * 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 Set();
+  /** 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;
+  }
+  leaseFor(runId) {
+    let lease = this.leases.get(runId);
+    if (!lease) {
+      lease = new BrowserLease({ isRevoked: (id) => this.revoked.has(id) });
+      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);
+  }
+  /**
+   * 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) {
+    const held = this.runs.get(runId);
+    if (!held) return;
+    this.runs.delete(runId);
+    this.closing.add(runId);
+    await this.teardown(runId, held);
+  }
+  /** Release every run's session. For when the deployment's config changes. */
+  async dispose() {
+    const ids = /* @__PURE__ */ new Set([...this.runs.keys(), ...this.opening]);
+    await Promise.all([...ids].map((runId) => this.endRun(runId)));
+  }
+  /** A worker finished; it will never ask for the browser again. */
+  actorEnded(actorId) {
+    for (const lease of this.leases.values()) lease.actorEnded(actorId);
+  }
+  /** 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);
+    this.closing.add(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);
+    this.closing.add(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);
+  }
+  /**
+   * 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.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.
+   */
+  async teardown(runId, held) {
+    try {
+      await this.disposeRun(runId, held);
+    } finally {
+      this.closing.delete(runId);
+    }
+  }
+  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 planned = this.runs.get(runId)?.generation ?? 0;
+    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." };
+    }
+    if (!await lease_.awaitActionSlot()) {
+      lease_.releaseIfHeldBy(actor);
+      return { ok: false, detail: "Another browser action is still finishing. Try again." };
+    }
+    const token = lease_.beginAction();
+    if (!token) {
+      return { ok: false, detail: "Another browser action is already running. Wait for it to finish." };
+    }
+    try {
+      const held = await this.open(runId, context.signal);
+      if (this.revoked.has(runId)) {
+        await this.releaseIfIdle(runId);
+        return { ok: false, detail: "The user stopped browser control for this run." };
+      }
+      if (context.signal?.aborted || held.abort.signal.aborted) {
+        await this.releaseIfIdle(runId);
+        return { ok: false, detail: "The run was cancelled." };
+      }
+      return await this.perform(held, action, planned);
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    } finally {
+      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) {
+    const existing = this.runs.get(runId);
+    if (existing && !existing.page.isClosed()) return existing;
+    if (existing) {
+      this.runs.delete(runId);
+      this.closing.add(runId);
+      await this.teardown(runId, existing);
+    }
+    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.`
+      );
+    }
+    this.opening.add(runId);
+    if (!this.aborts.has(runId)) this.aborts.set(runId, new AbortController());
+    try {
+      return await this.openReserved(runId, signal);
+    } 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);
+    this.announceLiveView(runId, session.liveViewUrl, true);
+    let browser;
+    let owned;
+    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.");
+      const held = { session, browser, page: page2, generation: 0, abort: abort2, ...owned ? { ownedContext: owned } : {} };
+      page2.on("framenavigated", ((frame) => {
+        if (frame !== page2.mainFrame()) return;
+        held.generation += 1;
+      }));
+      this.runs.set(runId, held);
+      return held;
+    } catch (err) {
+      this.announceLiveView(runId, void 0, false);
+      await owned?.close().catch(() => {
+      });
+      await browser?.close().catch(() => {
+      });
+      await this.provider.endSession(session.id).catch(() => {
+      });
+      throw err;
+    }
+  }
+  async perform(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 () => ({
+      url: page2.url(),
+      title: await page2.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":
+        await stoppable(page2.click(action.selector, { timeout }));
+        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": {
+        if (action.selector) await stoppable(page2.press(action.selector, action.key, { timeout }));
+        else await stoppable(page2.keyboard.press(action.key));
+        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 === "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.";
+}
+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 +36365,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 +36406,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 +36423,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 +36492,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;