cascade-ai 0.77.0 → 0.79.0

package/dist/cli.cjs

@@ -1849,7 +1849,7 @@ var CASCADE_VERSION, CASCADE_CONFIG_FILE, CASCADE_DB_FILE, CASCADE_DASHBOARD_SEC
 var init_constants = __esm({
   "src/constants.ts"() {
     init_pricing();
-    CASCADE_VERSION = "0.77.0";
+    CASCADE_VERSION = "0.79.0";
     CASCADE_CONFIG_FILE = ".cascade/config.json";
     CASCADE_DB_FILE = ".cascade/memory.db";
     CASCADE_DASHBOARD_SECRET_FILE = ".cascade/dashboard-secret";
@@ -15540,6 +15540,45 @@ var ToolsConfigSchema = zod.z.object({
   shellBlocklist: zod.z.array(zod.z.string()).default(["rm -rf", "sudo rm", "format", "mkfs"]),
   requireApprovalFor: zod.z.array(zod.z.string()).default([]),
   browserEnabled: zod.z.boolean().default(false),
+  /**
+   * Let a run ACT on the page open in the desktop's built-in browser — click,
+   * type, submit — not just read it.
+   *
+   * Distinct from `browserEnabled`, which turns on the headless Playwright
+   * tool. That one drives a throwaway browser with an empty cookie jar; this
+   * one drives the session the user is signed into, which is a different order
+   * of consequence and so gets its own switch rather than riding on that one.
+   *
+   * Off by default. Turning it on does not hand anything over silently: the
+   * tool still goes through the approval chain, and the browser panel carries a
+   * 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 */
@@ -21464,6 +21503,23 @@ Now execute your subtask using this context where relevant.`
       this.setStatus("FAILED", finalOutput);
       this.peerBus?.publish(this.id, assignment.subtaskId, finalOutput, "FAILED");
       return this.buildResult("ESCALATED", finalOutput, { checksRun, passed, failed }, issues, correctionAttempts);
+    } finally {
+      this.releaseBrowserControl();
+    }
+  }
+  /**
+   * End this worker's hold on the shared browser.
+   *
+   * Duck-typed rather than imported: `browser_control` is registered only by a
+   * host that HAS a browser (the desktop), so in the CLI and hosted runs there
+   * is no such tool and this is a no-op. Importing the class to instanceof-check
+   * it would couple the worker to a tool that usually is not there.
+   */
+  releaseBrowserControl() {
+    try {
+      const tool = this.toolRegistry.getTool?.("browser_control");
+      tool?.releaseActor?.(this.id);
+    } catch {
     }
   }
   sendToPeer(toId, content) {
@@ -31267,6 +31323,127 @@ var CurrentPageTool = class extends BaseTool {
   }
 };
 
+// src/tools/browser-control.ts
+var BrowserControlTool = class extends BaseTool {
+  name = "browser_control";
+  description = "Act on the web page the user has open in the built-in browser: navigate, click an element, type into a field, press a key, or wait for something to appear. This drives the REAL browser the user is signed into and can see, so actions have real consequences \u2014 prefer read_current_page when you only need to look. CSS selectors are matched against the live page; call extract_text first if you need to find one. There is one browser: if another part of this run is using it, this call waits its turn, so a slow reply means queued, not stuck.";
+  inputSchema = {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["navigate", "click", "fill", "press", "wait_for", "extract_text"],
+        description: "What to do."
+      },
+      url: { type: "string", description: "For navigate: the http(s) address to open." },
+      selector: {
+        type: "string",
+        description: "CSS selector for click, fill and wait_for. Optional for extract_text (defaults to the whole page)."
+      },
+      value: { type: "string", description: "For fill: the text to type." },
+      key: { type: "string", description: 'For press: a key name such as "Enter", "Tab" or "Escape".' },
+      timeoutMs: { type: "number", description: "For wait_for: how long to wait before giving up (default 10000, max 30000)." }
+    },
+    required: ["action"]
+  };
+  controller;
+  release;
+  /** One-way. See `revoke`. */
+  revoked = false;
+  constructor(controller, release) {
+    super();
+    this.controller = controller;
+    this.release = release;
+  }
+  /**
+   * A worker has finished. Ends its hold on the browser.
+   *
+   * Called from the tier's terminal path rather than by the model, because a
+   * model cannot be relied on to announce that it is done — which is why the
+   * host cannot use idle time as the boundary instead.
+   */
+  releaseActor(actorId) {
+    this.release?.(actorId);
+  }
+  /**
+   * Permanently disable this tool, whatever the registry still holds.
+   *
+   * Registration-time gates cannot express "this run turned out to be
+   * unattended": a host that wires the controller and only then declares the
+   * run unattended has already registered the tool, and a check that ran at
+   * registration has no second chance. Enforcing at EXECUTION time makes the
+   * guarantee independent of call order, which is the whole point of stating
+   * the invariant rather than relying on the scheduler's current sequence.
+   *
+   * One-way on purpose. A safety gate that can be re-opened by a later call is
+   * a gate that a refactor re-opens by accident.
+   */
+  revoke() {
+    this.revoked = true;
+  }
+  // Acting on a session the user is signed into is the highest-consequence
+  // thing in the tool set — higher than shell, arguably, because the blast
+  // radius is someone else's server rather than this machine.
+  isDangerous() {
+    return true;
+  }
+  async execute(input, options) {
+    if (this.revoked) {
+      return "Error: browser control is not available in this run. It requires a person watching who can stop it, and nobody is.";
+    }
+    const kind = input["action"];
+    if (!kind) return "Error: action is required.";
+    if (options?.signal?.aborted) return "Error: the run was cancelled before this action ran.";
+    const missing = requiredFieldFor(kind, input);
+    if (missing) return `Error: "${kind}" needs ${missing}.`;
+    const action = {
+      kind,
+      ...typeof input["url"] === "string" ? { url: input["url"] } : {},
+      ...typeof input["selector"] === "string" ? { selector: input["selector"] } : {},
+      ...typeof input["value"] === "string" ? { value: input["value"] } : {},
+      ...typeof input["key"] === "string" ? { key: input["key"] } : {},
+      ...typeof input["timeoutMs"] === "number" ? { timeoutMs: Math.min(Math.max(input["timeoutMs"], 0), 3e4) } : {}
+    };
+    let outcome;
+    try {
+      outcome = await this.controller(action, {
+        // `sessionId` is the run. The host scopes both revocation and its
+        // single-owner lease on it, so passing it is not telemetry — drop it
+        // and a Stop in one run silently stops every later one.
+        sessionId: options?.sessionId ?? "",
+        actorId: options?.tierId ?? options?.sessionId ?? "",
+        ...options?.signal ? { signal: options.signal } : {}
+      });
+    } catch (err) {
+      return `Error: the browser could not perform "${kind}" \u2014 ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const where = outcome.url ? `
+Page: ${outcome.title ? `${outcome.title} \u2014 ` : ""}${outcome.url}` : "";
+    return `${outcome.ok ? "" : "Failed: "}${outcome.detail}${where}`;
+  }
+};
+function requiredFieldFor(kind, input) {
+  const has = (k) => typeof input[k] === "string" && input[k].length > 0;
+  const given = (k) => typeof input[k] === "string";
+  switch (kind) {
+    case "navigate":
+      return has("url") ? null : "a url";
+    case "click":
+      return has("selector") ? null : "a selector";
+    case "fill":
+      return has("selector") ? given("value") ? null : "a value" : "a selector";
+    case "press":
+      return has("key") ? null : "a key";
+    case "wait_for":
+      return has("selector") ? null : "a selector";
+    // extract_text works with or without a selector.
+    case "extract_text":
+      return null;
+    default:
+      return null;
+  }
+}
+
 // src/core/cascade.ts
 var ESCALATION_DECISION_TIMEOUT_MS = 5 * 6e4;
 function buildContextualPrompt(prompt, history = []) {
@@ -31759,6 +31936,79 @@ ${input}` }],
     if ((this.config.tools?.disabledTools ?? []).includes("read_current_page")) return;
     this.toolRegistry.register(new CurrentPageTool(provider));
   }
+  /**
+   * True when nobody is watching this run — a scheduled/cron task, which
+   * auto-approves every tool because there is no one to ask.
+   *
+   * That auto-approval is fine for ordinary tools and disqualifying for this
+   * one: `browser_control` drives the signed-in browser, and "every run asks
+   * first" is the promise the Settings copy makes. The property used to hold
+   * only because `runScheduledTask` happens not to call `setBrowserController`
+   * — a guarantee resting on an ABSENT call, which is exactly what a later
+   * refactor adds without noticing. Stated and enforced instead.
+   */
+  unattended = false;
+  /**
+   * Declare that no human is watching this run, so capabilities that depend on
+   * a person being able to see and stop them are refused outright.
+   */
+  setUnattended(on) {
+    this.unattended = on;
+    if (!on) return;
+    const tool = this.toolRegistry.getTool("browser_control");
+    tool?.revoke?.();
+  }
+  /**
+   * Wire the host's browser so a run can ACT on the open page, not just read it.
+   *
+   * Two gates before this registers anything, and both matter:
+   *
+   *   - `tools.agentBrowserControl` must be on. Unlike read_current_page, which
+   *     reaches nothing the user has not already opened themselves, this drives
+   *     the session they are signed into. That is opt-in, not a default.
+   *   - `disabledTools` still removes it, the same as every other tool.
+   *   - The run must not be UNATTENDED. See `setUnattended`.
+   *
+   * Host-supplied like the page provider: the tool exists only where there is a
+   * real browser to drive, so it never has to be refused in the CLI or a hosted
+   * 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 (!enabled) return;
+    if ((this.config.tools?.disabledTools ?? []).includes("browser_control")) return;
+    this.toolRegistry.register(new BrowserControlTool(controller, release));
+  }
   registerMediaTools(workspacePath) {
     const denied = new Set(this.config.tools?.disabledTools ?? []);
     const permitted = (name) => !denied.has(name);
@@ -32364,6 +32614,7 @@ ${prompt}` : prompt;
     this.router.setRunSignal(options.signal);
     const startMs = Date.now();
     const taskId = crypto.randomUUID();
+    this.emit("run:started", { taskId });
     this.decisionLog = [];
     this.currentRunCompleted = [];
     this.wroteCheckpointThisRun = false;
@@ -38231,6 +38482,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) => {
@@ -38261,6 +38526,7 @@ function applySettingsPayload(config, data) {
     if (["auto", "T1", "T2", "T3"].includes(a["forceTier"])) config.routing = { ...config.routing ?? {}, forceTier: a["forceTier"] };
     if (typeof a["benchmarksLive"] === "boolean") config.benchmarks = { ...config.benchmarks ?? {}, live: a["benchmarksLive"] };
     if (["isolate", "worker", "auto"].includes(a["dynamicToolSandbox"])) config.tools = { ...config.tools ?? {}, dynamicToolSandbox: a["dynamicToolSandbox"] };
+    if (typeof a["agentBrowserControl"] === "boolean") config.tools = { ...config.tools ?? {}, agentBrowserControl: a["agentBrowserControl"] };
     if (typeof a["factsExtraction"] === "boolean") config.knowledge = { ...config.knowledge ?? {}, factsExtraction: a["factsExtraction"] };
     if (typeof a["rememberSessions"] === "boolean") config.memory = { ...config.memory ?? {}, rememberSessions: a["rememberSessions"] };
     if (typeof a["enableToolCreation"] === "boolean") config.enableToolCreation = a["enableToolCreation"];
@@ -38276,6 +38542,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: {
@@ -38305,6 +38572,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,
@@ -38318,6 +38594,7 @@ function settingsSnapshot(config) {
       forceTier: config.routing?.forceTier,
       benchmarksLive: config.benchmarks?.live,
       dynamicToolSandbox: config.tools?.dynamicToolSandbox,
+      agentBrowserControl: config.tools?.agentBrowserControl,
       factsExtraction: config.knowledge?.factsExtraction,
       rememberSessions: config.memory?.rememberSessions,
       enableToolCreation: config.enableToolCreation,
@@ -38828,6 +39105,14 @@ var DashboardServer = class {
    * always failing.
    */
   currentPageProvider;
+  /**
+   * Supplied by the desktop shell so a run can ACT on that page — click, type,
+   * submit — not just read it. Same reasoning as the provider above: absent in
+   * the CLI, so the tool is not registered rather than present and failing.
+   * Cascade applies the `tools.agentBrowserControl` gate on top of this.
+   */
+  browserController;
+  browserActorRelease;
   activeControllers = /* @__PURE__ */ new Map();
   /**
    * Run taskIds per chat session — file snapshots are keyed by the run's
@@ -38889,6 +39174,7 @@ var DashboardServer = class {
     });
     this.socket.onConfigUpdate(async (data) => {
       const result = await commitSettings(this.config, data, (committed) => this.persistConfig(committed));
+      if (result.ok) this.settingsChangeHook?.(this.config);
       const refused = result.refused.map((r) => ({
         type: r.type,
         reason: r.reason,
@@ -38912,6 +39198,7 @@ var DashboardServer = class {
       const cascade = new Cascade(cfg, this.workspacePath, this.store);
       this.activeSessions.set(sessionId, cascade);
       if (this.currentPageProvider) cascade.setCurrentPageProvider(this.currentPageProvider);
+      if (this.browserController) cascade.setBrowserController(this.browserController, this.browserActorRelease);
       cascade.on("stream:token", (e) => {
         this.emitToSessionClients(socketId, sessionId, "stream:token", { sessionId, tierId: e.tierId, text: e.text, primary: e.primary });
       });
@@ -38935,13 +39222,16 @@ var DashboardServer = class {
         if (ev.requestId) this.clearPendingEscalation(ev.requestId);
         this.emitToSessionClients(socketId, sessionId, "escalation:timeout", { sessionId, ...e });
       });
+      cascade.on("run:started", (e) => {
+        const id = e.taskId;
+        if (id) this.recordSessionTask(sessionId, id);
+      });
       try {
         const result = await cascade.run({
           prompt: runPrompt,
           signal: abortController.signal,
           approvalCallback: this.makeApprovalCallback(sessionId)
         });
-        this.recordSessionTask(sessionId, result.taskId);
         this.persistRunEnd(sessionId, title, prompt, result.output, "COMPLETED", result);
         this.captureWhy(sessionId, cascade, result);
         this.emitToSessionClients(socketId, sessionId, "session:complete", { sessionId, result });
@@ -39007,6 +39297,49 @@ var DashboardServer = class {
   setCurrentPageProvider(provider) {
     this.currentPageProvider = provider;
   }
+  /** Let runs act on that view, not just read it (desktop only). */
+  setBrowserController(controller, release) {
+    this.browserController = controller;
+    this.browserActorRelease = release;
+  }
+  /**
+   * Told whenever settings are committed through THIS server.
+   *
+   * Settings reach the live config by two routes — the desktop's Electron IPC
+   * handler and this server's `config:update` socket — and both run the same
+   * `commitSettings`. The desktop mirrors `tools.agentBrowserControl` into its
+   * browser module after its own route, but had no way to learn about the
+   * other, so a socket write left the module's copy stale: an enable the module
+   * still refused, or worse a disable the module still honoured for a run
+   * already holding the tool. This is the same sibling-writer drift
+   * `settings-payload.ts` exists to prevent, one layer up.
+   */
+  settingsChangeHook;
+  onSettingsChanged(hook) {
+    this.settingsChangeHook = hook;
+  }
+  /**
+   * Told when a run ends, so a host holding run-scoped state can release it.
+   *
+   * The desktop uses this to retire a run's browser Stop control: that has to
+   * outlive each individual action (the gap between two actions is when the
+   * user most wants it) but must not outlive the run.
+   */
+  /**
+   * Fired when a run ends, carrying BOTH identifiers explicitly.
+   *
+   * They are different things and conflating them was a live bug: a chat
+   * `sessionId` can contain many runs (hence `sessionTaskIds`), while
+   * `Cascade.run()` mints a fresh random `taskId` per run — and it is the
+   * taskId that tools see as `ToolExecuteOptions.sessionId`. Passing only the
+   * chat id meant browser cleanup keyed on the task id matched nothing, so a
+   * finished run kept its Stop banner armed and held its browser lease until
+   * the deadlock ceiling.
+   */
+  runEndedHook;
+  onRunEnded(hook) {
+    this.runEndedHook = hook;
+  }
   async start() {
     const isLoopback = this.host === "127.0.0.1" || this.host === "::1" || this.host === "localhost";
     if (!isLoopback) {
@@ -39197,6 +39530,8 @@ var DashboardServer = class {
   }
   /** Record run end: the assistant reply (when there is one) and the runtime row's final status. */
   persistRunEnd(sessionId, title, latestPrompt, reply, status, result) {
+    const endedTaskId = result?.taskId ?? this.sessionTaskIds.get(sessionId)?.at(-1);
+    this.runEndedHook?.({ sessionId, ...endedTaskId ? { taskId: endedTaskId } : {} });
     try {
       if (reply && reply.trim()) {
         this.store.addMessage({ id: crypto.randomUUID(), sessionId, role: "assistant", content: reply, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
@@ -39290,6 +39625,7 @@ var DashboardServer = class {
     const prompt = task.prompt;
     const title = this.persistRunStart(sessionId, `[${task.name}] ${prompt}`);
     const cascade = new Cascade(this.config, task.workspacePath ?? this.workspacePath, this.store);
+    cascade.setUnattended(true);
     this.activeSessions.set(sessionId, cascade);
     cascade.on("tier:status", (e) => {
       this.socket.broadcast("tier:status", { sessionId, ...e });
@@ -39297,13 +39633,16 @@ var DashboardServer = class {
     cascade.on("peer:message", (e) => {
       this.socket.emitPeerMessage(e);
     });
+    cascade.on("run:started", (e) => {
+      const id = e.taskId;
+      if (id) this.recordSessionTask(sessionId, id);
+    });
     try {
       const result = await cascade.run({
         prompt,
         identityId: task.identityId,
         approvalCallback: async () => ({ approved: true, always: false })
       });
-      this.recordSessionTask(sessionId, result.taskId);
       this.persistRunEnd(sessionId, title, prompt, result.output, "COMPLETED", result);
       this.captureWhy(sessionId, cascade, result);
       this.socket.broadcast("session:complete", { sessionId, result });
@@ -39936,6 +40275,7 @@ ${prompt}`;
         const cascade = new Cascade(this.config, this.workspacePath, this.store);
         this.activeSessions.set(sessionId, cascade);
         if (this.currentPageProvider) cascade.setCurrentPageProvider(this.currentPageProvider);
+        if (this.browserController) cascade.setBrowserController(this.browserController, this.browserActorRelease);
         cascade.on("stream:token", (e) => {
           this.socket.broadcastToRoom(`session:${sessionId}`, "stream:token", { sessionId, tierId: e.tierId, text: e.text, primary: e.primary });
         });
@@ -39959,13 +40299,16 @@ ${prompt}`;
           if (ev.requestId) this.clearPendingEscalation(ev.requestId);
           this.socket.broadcastToRoom(`session:${sessionId}`, "escalation:timeout", { sessionId, ...e });
         });
+        cascade.on("run:started", (e) => {
+          const id = e.taskId;
+          if (id) this.recordSessionTask(sessionId, id);
+        });
         try {
           const result = await cascade.run({
             prompt: runPrompt,
             identityId: body.identityId,
             approvalCallback: this.makeApprovalCallback(sessionId)
           });
-          this.recordSessionTask(sessionId, result.taskId);
           this.persistRunEnd(sessionId, title, prompt, result.output, "COMPLETED", result);
           this.captureWhy(sessionId, cascade, result);
           this.socket.broadcast("cost:update", {