cascade-ai 0.77.0 → 0.78.0

package/dist/index.cjs

@@ -11669,7 +11669,7 @@ function reconcilePrice(model, live) {
 }
 
 // src/constants.ts
-var CASCADE_VERSION = "0.77.0";
+var CASCADE_VERSION = "0.78.0";
 var CASCADE_CONFIG_DIR = ".cascade";
 var CASCADE_MD_FILE = "CASCADE.md";
 var CASCADE_IGNORE_FILE = ".cascadeignore";
@@ -16130,6 +16130,20 @@ 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),
   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 */
@@ -20914,6 +20928,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) {
@@ -30730,6 +30761,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 = []) {
@@ -31222,6 +31374,49 @@ ${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) {
+    if (this.unattended) return;
+    if (!this.config.tools?.agentBrowserControl) 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);
@@ -31827,6 +32022,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;
@@ -32592,6 +32788,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"];
@@ -32649,6 +32846,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,
@@ -33153,6 +33351,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
@@ -33214,6 +33420,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,
@@ -33237,6 +33444,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 });
       });
@@ -33260,13 +33468,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 });
@@ -33332,6 +33543,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) {
@@ -33522,6 +33776,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() });
@@ -33615,6 +33871,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 });
@@ -33622,13 +33879,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 });
@@ -34261,6 +34521,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 });
         });
@@ -34284,13 +34545,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", {
@@ -35333,6 +35597,7 @@ function applySyncBundle(bundle, config, cleanup) {
 exports.AZURE_BASE_MODELS = AZURE_BASE_MODELS;
 exports.AZURE_BASE_URL_TEMPLATE = AZURE_BASE_URL_TEMPLATE;
 exports.AuditLogger = AuditLogger;
+exports.BrowserControlTool = BrowserControlTool;
 exports.CASCADE_AUDIT_FILE = CASCADE_AUDIT_FILE;
 exports.CASCADE_CONFIG_DIR = CASCADE_CONFIG_DIR;
 exports.CASCADE_CONFIG_FILE = CASCADE_CONFIG_FILE;