cascade-ai 0.79.0 → 0.81.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.79.0";
+    CASCADE_VERSION = "0.81.0";
     CASCADE_CONFIG_FILE = ".cascade/config.json";
     CASCADE_DB_FILE = ".cascade/memory.db";
     CASCADE_DASHBOARD_SECRET_FILE = ".cascade/dashboard-secret";
@@ -31444,8 +31444,95 @@ function requiredFieldFor(kind, input) {
   }
 }
 
+// src/tools/ask-user.ts
+var MAX_QUESTIONS = 5;
+var MAX_OPTIONS = 6;
+var AskUserTool = class extends BaseTool {
+  name = "ask_user";
+  description = "Ask the person a short questionnaire when their request is genuinely ambiguous, instead of guessing. Use it when two readings of the request would produce materially different work \u2014 which account, which date range, whether to include drafts \u2014 and NOT for anything you can settle yourself or from the conversation. Ask everything you need in ONE call: several questions together read as a form, the same questions one per turn read as an interrogation. You may get no answer (nobody is watching, or they did not reply); if so, proceed on your best reading and say which assumption you made.";
+  inputSchema = {
+    type: "object",
+    properties: {
+      questions: {
+        type: "array",
+        minItems: 1,
+        maxItems: MAX_QUESTIONS,
+        description: `The questions to ask together (at most ${MAX_QUESTIONS}).`,
+        items: {
+          type: "object",
+          properties: {
+            prompt: { type: "string", description: "The question, as you would say it to them." },
+            kind: {
+              type: "string",
+              enum: ["choice", "multi", "text"],
+              description: "choice = pick one, multi = pick any that apply, text = free-form answer."
+            },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: `The answers to offer, for choice and multi (at most ${MAX_OPTIONS}). Omit for text.`
+            }
+          },
+          required: ["prompt", "kind"]
+        }
+      }
+    },
+    required: ["questions"]
+  };
+  ask;
+  constructor(ask) {
+    super();
+    this.ask = ask;
+  }
+  // Asking a question changes nothing, so it needs no approval gate: a prompt
+  // asking permission to show a prompt is a tax on the behaviour we want.
+  isDangerous() {
+    return false;
+  }
+  async execute(input, options) {
+    const raw = Array.isArray(input["questions"]) ? input["questions"] : [];
+    const questions = [];
+    for (const [i, q] of raw.slice(0, MAX_QUESTIONS).entries()) {
+      const item = q ?? {};
+      const prompt = typeof item["prompt"] === "string" ? item["prompt"].trim() : "";
+      if (!prompt) continue;
+      const kind = item["kind"] === "multi" || item["kind"] === "text" ? item["kind"] : "choice";
+      const options_ = Array.isArray(item["options"]) ? item["options"].filter((o) => typeof o === "string" && o.trim() !== "").slice(0, MAX_OPTIONS) : [];
+      const resolved = kind !== "text" && options_.length < 2 ? "text" : kind;
+      questions.push({
+        // Positional, and assigned HERE. Letting the model supply ids invites
+        // two questions sharing one, and the second answer would overwrite the
+        // first with nothing to say it had.
+        id: `q${i + 1}`,
+        prompt,
+        kind: resolved,
+        ...resolved === "text" ? {} : { options: options_ }
+      });
+    }
+    if (questions.length === 0) {
+      return "Error: ask_user needs at least one question with a prompt.";
+    }
+    const result = await this.ask(questions, options.signal);
+    if (result.outcome !== "answered" || result.answers.length === 0) {
+      const why = result.outcome === "no-listener" ? "There is nobody watching this run to answer" : result.outcome === "aborted" ? "The run was stopped while the question was open" : result.outcome === "answered" ? "They saw the questions and chose not to answer" : "They did not answer in time";
+      return `${why}. Proceed on your best reading of the request, and say plainly which assumption you made.`;
+    }
+    const byId = new Map(result.answers.map((a) => [a.id, a.value]));
+    const lines = questions.map((q) => {
+      const value = byId.get(q.id);
+      const said = Array.isArray(value) ? value.join(", ") : value;
+      return `${q.prompt}
+  \u2192 ${said && said.length > 0 ? said : "(no answer given)"}`;
+    });
+    return `They answered:
+
+${lines.join("\n\n")}`;
+  }
+};
+
 // src/core/cascade.ts
 var ESCALATION_DECISION_TIMEOUT_MS = 5 * 6e4;
+var CLARIFICATION_TIMEOUT_MS = 2 * 6e4;
 function buildContextualPrompt(prompt, history = []) {
   const recent = history.slice(-6);
   if (recent.length === 0) return prompt;
@@ -31724,6 +31811,112 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
   // timeout. Same class of bug as the twelve-failover dead-model race: a wave
   // is concurrent, so per-run singletons are never safe inside it.
   pendingEscalations = /* @__PURE__ */ new Map();
+  /**
+   * Questionnaires waiting on a person, keyed by request id.
+   *
+   * Exactly the shape `pendingEscalations` uses, and for the same reason: the
+   * answer, the timeout and the abort all race, and one settle path guarded by
+   * the map delete is what makes the first of them win.
+   */
+  pendingClarifications = /* @__PURE__ */ new Map();
+  /**
+   * Put a gate's opening question to its listeners, and NOTICE when one fails.
+   *
+   * `emit` cannot do this job. It calls listeners synchronously and discards
+   * what they return, so an `async` listener — the ordinary shape for anything
+   * that has to reach a socket or a UI — does not fail in a way `emit` reports:
+   * it returns a REJECTED PROMISE that nobody is holding. The `try` around the
+   * emit sees nothing, the gate is never told delivery failed, and it parks for
+   * its full timeout while Node raises an unhandled rejection that can take the
+   * process down.
+   *
+   * `onFailed` is called for either shape, and it is safe to call more than
+   * once: both gates route it to `settle`, which is guarded by a map delete, so
+   * the first failure wins and the rest are no-ops.
+   *
+   * PER LISTENER, not around the loop. `emit` stops dispatching at the first
+   * throw, so one broken host used to cost a working one its notification —
+   * the same reason `announceLiveView` delivers its two listeners separately.
+   * A synchronous failure settles the gate once the whole snapshot has been
+   * delivered; an asynchronous one settles it when the rejection arrives, which
+   * is still far better than the window-long park it replaces.
+   *
+   * SETTLED AFTER THE LOOP, not inside it, and that is not tidiness. `onFailed`
+   * settles the gate, and settling emits the gate's CLOSURE — so failing
+   * mid-dispatch announced "this request is over" and then went on handing the
+   * OPENING event to the listeners after it. A host later in the list would
+   * draw a form whose only closure notification had already gone past, and it
+   * would stand there forever. Deliver to everyone, then decide.
+   *
+   * `rawListeners`, NOT `listeners`. Bypassing `emit` means taking on what
+   * `emit` was doing, and `once` is the part that bites: `listeners()` hands
+   * back the UNWRAPPED callback, so calling it never runs the wrapper that
+   * deregisters it. A host that asked to be told once would be told every
+   * time — and told through a transport it had set up for one gate only.
+   * `rawListeners()` returns the wrapper, which removes the registration and
+   * passes the underlying listener's return value straight through, so the
+   * promise below is still the one being observed. Verified against Node.
+   *
+   * `.call(this, …)`, which is the third thing `emit` was doing. EventEmitter
+   * invokes listeners with the emitter as the receiver, so
+   * `function () { this.resolveClarification(...) }` is a legitimate host — and
+   * calling it bare gave it `this === undefined`, which throws, which this
+   * would then have read as the host failing to receive the question and
+   * settled the gate unanswered. A working listener turned into a delivery
+   * failure by the thing delivering it.
+   */
+  deliverGate(event, payload, onFailed) {
+    let delivered = false;
+    let threw = false;
+    const pending = [];
+    for (const listener of this.rawListeners(event)) {
+      try {
+        const out = listener.call(this, payload);
+        if (out && typeof out.then === "function") {
+          pending.push(Promise.resolve(out).then(() => true, () => false));
+        } else {
+          delivered = true;
+        }
+      } catch {
+        threw = true;
+      }
+    }
+    if (delivered) return;
+    if (pending.length === 0) {
+      if (threw) onFailed();
+      return;
+    }
+    void Promise.all(pending).then((results) => {
+      if (!results.some(Boolean)) onFailed();
+    });
+  }
+  /**
+   * Tell listeners something that is over, and let none of them make it worse.
+   *
+   * The closing half of the gate family — `clarification:closed`,
+   * `clarification:timeout`, `escalation:closed`, `escalation:timeout`. Each
+   * was already wrapped in a `try` for the synchronous case, and each had the
+   * same hole `deliverGate` had before last round: `emit` discards what a
+   * listener returns, so an `async` host fails by returning a rejected promise
+   * nobody is holding and Node raises an unhandled rejection.
+   *
+   * There is nothing to settle here — the gate is already closed, which is the
+   * whole message — so unlike `deliverGate` this reports to no one. It exists
+   * so that the four informational emits cannot take the process down, and so
+   * the rule is written once rather than four times.
+   */
+  announceGateClosed(event, payload) {
+    for (const listener of this.rawListeners(event)) {
+      try {
+        const out = listener.call(this, payload);
+        if (out && typeof out.then === "function") {
+          void Promise.resolve(out).catch(() => {
+          });
+        }
+      } catch {
+      }
+    }
+  }
   async requestEscalationDecision(ctx, taskId, signal) {
     if (this.config.autonomy === "auto") return { action: "skip", automatic: true };
     if (this.listenerCount("escalation:decision-required") === 0) return { action: "skip", automatic: true };
@@ -31736,23 +31929,28 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
         if (timeout) clearTimeout(timeout);
         signal?.removeEventListener("abort", onAbort);
         resolve2(decision);
+        this.announceGateClosed("escalation:closed", { taskId, requestId, sectionId: ctx.sectionId });
       };
       const onAbort = () => settle({ action: "skip", automatic: true });
       signal?.addEventListener("abort", onAbort, { once: true });
       timeout = setTimeout(() => {
-        this.emit("escalation:timeout", { taskId, requestId, sectionId: ctx.sectionId });
         settle({ action: "timeout" });
+        this.announceGateClosed("escalation:timeout", { taskId, requestId, sectionId: ctx.sectionId });
       }, ESCALATION_DECISION_TIMEOUT_MS);
       this.pendingEscalations.set(requestId, settle);
-      this.emit("escalation:decision-required", {
-        taskId,
-        requestId,
-        sectionId: ctx.sectionId,
-        sectionTitle: ctx.sectionTitle,
-        issues: ctx.issues,
-        summary: ctx.summary,
-        timeoutMs: ESCALATION_DECISION_TIMEOUT_MS
-      });
+      this.deliverGate(
+        "escalation:decision-required",
+        {
+          taskId,
+          requestId,
+          sectionId: ctx.sectionId,
+          sectionTitle: ctx.sectionTitle,
+          issues: ctx.issues,
+          summary: ctx.summary,
+          timeoutMs: ESCALATION_DECISION_TIMEOUT_MS
+        },
+        () => settle({ action: "skip", automatic: true })
+      );
     });
   }
   /**
@@ -31789,6 +31987,73 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
   releasePendingEscalations(action = "skip") {
     for (const settle of Array.from(this.pendingEscalations.values())) settle({ action, automatic: true });
   }
+  // ── Clarification: asking instead of assuming ───────────────────────
+  // The same gate shape as the escalation above, and for the same reasons. The
+  // difference that matters: an unanswered escalation SKIPS a section, while an
+  // unanswered question just means the model proceeds on its own reading — so
+  // every non-answer here is benign, and none of them may park the run.
+  /**
+   * Put a questionnaire to whoever is watching, if anybody is.
+   *
+   * Returns `no-listener` rather than waiting when there is nothing attached to
+   * answer — a scheduled run, an API caller with no socket, an autonomous run
+   * that has already said it wants no prompts. That check is the whole reason
+   * this can be offered to the model at all: a tool that might hang a headless
+   * run forever is a tool that cannot be registered.
+   */
+  async askUser(questions, signal) {
+    const none = (outcome) => ({ outcome, answers: [] });
+    if (this.unattended) return none("no-listener");
+    if (this.config.autonomy === "auto") return none("no-listener");
+    if (this.listenerCount("clarification:required") === 0) return none("no-listener");
+    if (signal?.aborted) return none("aborted");
+    const requestId = crypto.randomUUID();
+    return await new Promise((resolve2) => {
+      let timeout;
+      const settle = (result) => {
+        if (!this.pendingClarifications.delete(requestId)) return;
+        if (timeout) clearTimeout(timeout);
+        signal?.removeEventListener("abort", onAbort);
+        resolve2(result);
+        this.announceGateClosed("clarification:closed", { requestId });
+      };
+      const onAbort = () => settle(none("aborted"));
+      signal?.addEventListener("abort", onAbort, { once: true });
+      timeout = setTimeout(() => {
+        settle(none("timeout"));
+        this.announceGateClosed("clarification:timeout", { requestId });
+      }, CLARIFICATION_TIMEOUT_MS);
+      this.pendingClarifications.set(requestId, settle);
+      this.deliverGate(
+        "clarification:required",
+        { requestId, questions, timeoutMs: CLARIFICATION_TIMEOUT_MS },
+        () => settle(none("no-listener"))
+      );
+    });
+  }
+  /**
+   * Answer a questionnaire from a REPL / dashboard / cloud listener.
+   *
+   * `requestId` comes back on the `clarification:required` event and is what
+   * makes an answer land on the question that asked. Optional for a host with
+   * only one in flight, matching `resolveEscalation`: without it the oldest
+   * outstanding request is answered, which is correct whenever there is one.
+   */
+  resolveClarification(answers, requestId) {
+    const result = { outcome: "answered", answers };
+    if (requestId) {
+      this.pendingClarifications.get(requestId)?.(result);
+      return;
+    }
+    const oldest = this.pendingClarifications.keys().next();
+    if (!oldest.done) this.pendingClarifications.get(oldest.value)?.(result);
+  }
+  /** Release every parked questionnaire — run teardown, so none outlive the run. */
+  releasePendingClarifications() {
+    for (const settle of Array.from(this.pendingClarifications.values())) {
+      settle({ outcome: "aborted", answers: [] });
+    }
+  }
   /**
    * Resolve a pending boardroom plan approval from a REPL / dashboard listener.
    * An optional `note` re-plans and re-asks; an optional `editedPlan` is applied
@@ -31813,12 +32078,14 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
       const timeout = setTimeout(() => {
         if (this.pendingContextApproval) {
           this.pendingContextApproval = void 0;
+          this.announceGateClosed("context:approval-closed", {});
           resolve2(true);
         }
       }, 12e4);
       this.pendingContextApproval = (approved) => {
         clearTimeout(timeout);
         this.pendingContextApproval = void 0;
+        this.announceGateClosed("context:approval-closed", {});
         resolve2(approved);
       };
       this.emit("context:approval-required", info);
@@ -32009,6 +32276,34 @@ ${input}` }],
     if ((this.config.tools?.disabledTools ?? []).includes("browser_control")) return;
     this.toolRegistry.register(new BrowserControlTool(controller, release));
   }
+  /**
+   * Declare that this host can put a questionnaire to a person and answer it.
+   *
+   * Explicit, and NOT done at construction, because registering a tool is a
+   * promise the host has to keep. A host that registers `ask_user` without
+   * listening for `clarification:required` gives the model a tool that always
+   * answers "there is nobody watching this run" — while a person sits at the
+   * terminal looking at it. That is worse than not offering the tool at all:
+   * it costs a round trip and then tells the model something false.
+   *
+   * Only `cloud/server` bridges the protocol today. The CLI REPL and the
+   * dashboard do not, so they do not call this, and their models are not shown
+   * a capability nobody can serve. Wiring either of them is a matter of
+   * listening for the event and calling `resolveClarification`, then calling
+   * this.
+   *
+   * Still gated on the same conditions as the call itself, and `askUser`
+   * re-checks them: `setUnattended` can land after this, so the tool can be
+   * registered for a run that later turns out to have nobody on it. Then it
+   * answers `no-listener` and the model proceeds on its own reading, which is
+   * the same defence-in-depth `BrowserControlTool.revoke` provides.
+   */
+  enableClarification() {
+    if (this.unattended) return;
+    if (this.config.autonomy === "auto") return;
+    if ((this.config.tools?.disabledTools ?? []).includes("ask_user")) return;
+    this.toolRegistry.register(new AskUserTool((questions, signal) => this.askUser(questions, signal)));
+  }
   registerMediaTools(workspacePath) {
     const denied = new Set(this.config.tools?.disabledTools ?? []);
     const permitted = (name) => !denied.has(name);
@@ -32954,6 +33249,10 @@ ${finalOutput}` : ""
         this.releasePendingEscalations();
       } catch {
       }
+      try {
+        this.releasePendingClarifications();
+      } catch {
+      }
       this.router.restoreTierModels();
       this.router.setRunSignal(void 0);
       if (this.taskAnalyzer) {