cascade-ai 0.78.0 → 0.79.0

package/dist/index.js

@@ -11623,7 +11623,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";
@@ -16098,6 +16098,31 @@ var ToolsConfigSchema = z.object({
    * stop control for the run that is acting.
    */
   agentBrowserControl: 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: z.object({
+    /** `cdp` for an endpoint you run; `steel` for a Steel deployment. */
+    provider: z.enum(["cdp", "steel"]).optional(),
+    /** The websocket endpoint for `cdp`, or the API base for `steel`. */
+    url: z.string().optional(),
+    apiKey: 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: z.number().int().min(1).max(16).default(1)
+  }).optional(),
   mcpServers: z.array(McpServerConfigSchema).optional(),
   mcpTrusted: z.array(z.string()).optional(),
   /** Web search backends — at least one should be configured for best results */
@@ -31366,8 +31391,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));
   }
@@ -32712,6 +32767,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) => {
@@ -32758,6 +32827,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: {
@@ -32787,6 +32857,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,
@@ -34897,6 +34976,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) {
@@ -35548,6 +36315,6 @@ function applySyncBundle(bundle, config, cleanup) {
   return next;
 }
 
-export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, AuditLogger, BrowserControlTool, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN2 as CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, CascadeConfigSchema, CascadeIgnore, CascadeRouter, CascadeToolError, CloudClient, CodeSearchTool, ConfigManager, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, DashboardServer, DependencyScheduler, FileMcpOAuthStore, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, GraphRetriever, GraphSearchTool, HooksRunner, Keystore, LLMReranker, LM_STUDIO_BASE_URL, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, McpClient, McpOAuthProvider, MemoryStore, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, PROVIDER_DISPLAY_NAMES, RESUME_SCHEMA_VERSION, ResumeStore, Retriever, SqliteVectorStore, T1Administrator, T1_MODEL_PRIORITY, T2Manager, T2_MODEL_PRIORITY, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, TaskGraphValidationError, TaskScheduler, Telemetry, ToolRegistry, VISION_MODEL_PRIORITY, WorkspaceIndex, applyEndpointEdit, applyProviderApiKey, applyProviderCredential, applySettingsCredentials, applySettingsPayload, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText2 as chunkText, commitSettings, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, credentialDispositionForEdit, credentialEndpointIdentity, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, endpointFromSettingsPayload, evaluateAcceptance, explainRefusal, extractCharts, failures, fileExt, fileOAuthProvider, gatherSyncBundle, hasDefaultEndpoint, hasProviderCredential, hasUsableProvider, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, normalizeEndpoint, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, priorAzureRow, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sameAzureEndpoint, sameCredentialEndpoint, sameEndpoint, sessionWorthRemembering, settingsSnapshot, sniffImage, splitSlides, streamCascade, stripInline, summarizeCompleted, undecided, uniqueMcpServerName };
+export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, AuditLogger, BrowserControlTool, BrowserLease, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN2 as CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, CascadeConfigSchema, CascadeIgnore, CascadeRouter, CascadeToolError, CloudClient, CodeSearchTool, ConfigManager, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, DashboardServer, DependencyScheduler, FileMcpOAuthStore, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, GenericCdpProvider, GraphRetriever, GraphSearchTool, HooksRunner, Keystore, LLMReranker, LM_STUDIO_BASE_URL, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, McpClient, McpOAuthProvider, MemoryStore, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, PROVIDER_DISPLAY_NAMES, RESUME_SCHEMA_VERSION, RemoteBrowserController, ResumeStore, Retriever, SqliteVectorStore, SteelProvider, T1Administrator, T1_MODEL_PRIORITY, T2Manager, T2_MODEL_PRIORITY, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, TaskGraphValidationError, TaskScheduler, Telemetry, ToolRegistry, VISION_MODEL_PRIORITY, WorkspaceIndex, applyEndpointEdit, applyProviderApiKey, applyProviderCredential, applySettingsCredentials, applySettingsPayload, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText2 as chunkText, commitSettings, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, credentialDispositionForEdit, credentialEndpointIdentity, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, endpointFromSettingsPayload, evaluateAcceptance, explainRefusal, extractCharts, failures, fileExt, fileOAuthProvider, gatherSyncBundle, hasDefaultEndpoint, hasProviderCredential, hasUsableProvider, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isCdpEndpoint, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, normalizeEndpoint, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, priorAzureRow, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sameAzureEndpoint, sameCredentialEndpoint, sameEndpoint, sessionWorthRemembering, settingsSnapshot, sniffImage, splitSlides, streamCascade, stripInline, summarizeCompleted, undecided, uniqueMcpServerName };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map