switchroom 0.14.12 → 0.14.13

package/telegram-plugin/permission-title.ts

@@ -1,46 +1,35 @@
 /**
- * Build the inline-keyboard permission approval message — title + body.
+ * Human-readable text for the Telegram permission approval card.
  *
- * Two related concerns:
+ * The operator is (often) non-technical. A card must read as a plain
+ * sentence — "Gymbro wants to edit: supplement-log.md" — never a raw
+ * tool identifier (`mcp__perplexity__search`, `Edit:`). Two surfaces:
  *
- *   `summarizeToolForTitle` (one line, no escaping) is the bare summary
- *   used in the always-allow rule label and as the body-builder's
- *   internal building block. Pre-#186 the title was always `🔐
- *   Permission: ${toolName}` — for a `Skill` or `Bash` call the user
- *   couldn't tell which skill / command was being approved without
- *   tapping "See more".
+ *   `formatPermissionCardBody` — the card itself: a one-line natural
+ *   title plus the agent's stated reason. No tool ids, no scope chrome
+ *   (scope only appears once the operator taps "🔁 Always…").
  *
- *   `formatPermissionCardBody` (multi-line, HTML-escaped for
- *   parse_mode=HTML) is the body of the card itself. Pre-#1790 the
- *   collapsed card was a single line — operators had to tap "See more"
- *   to see the agent's stated reason or input preview. This mirrors
- *   the vault `vault_request_access` card's three-line layout (the
- *   gold standard) so every approval surface answers "what" + "why"
- *   without an expand tap.
+ *   `describeGrant` — the confirmation after a grant lands: "Gymbro can
+ *   now edit any file without asking" — phrased from the *scope the
+ *   operator chose*, so the breadth of an always-allow is legible after
+ *   the fact, not just before.
  *
- * See #186 (title) and #1790 (body).
+ * See #186 (title), #1790 (reason line), and the scoped-card work.
  */
 
 import { basename } from "node:path";
+import { prettyMcpServer, type ScopeOption } from "./permission-rule.js";
 
-const COMMAND_TITLE_MAX = 40;
-const PATH_TITLE_MAX = 40;
+const COMMAND_TITLE_MAX = 48;
 const DESCRIPTION_LINE_MAX = 240;
-const INPUT_VALUE_MAX = 60;
 
 /**
- * Human-friendly descriptions for switchroom-managed MCP tools. The
- * raw `mcp__<server>__<tool>` name is operator-unfriendly — they shouldn't
- * have to decode the namespace to understand what the agent is asking
- * to do. Use this map to turn the code-level identifier into a verb
- * phrase ("Read its own merged config" instead of
- * "mcp__agent-config__config_get") for the approval card.
- *
- * Note: post-#1215 these tools are pre-allowed in scaffolded
- * settings.permissions.allow, so the card should fire rarely.
- * This map is for the fallback path — agents the operator
- * narrowed the allowlist on, or tools added in future PRs that
- * haven't shipped the allowlist bump yet.
+ * Human verb-phrases for switchroom-managed MCP tools. The raw
+ * `mcp__<server>__<tool>` name is operator-hostile. Phrases are written
+ * to slot in after "wants to" / "can now" — e.g. "read its own merged
+ * config". Internal-server tools (agent-config / hostd / hindsight /
+ * telegram) read fine alone; external integrations get a "(Server)" tag
+ * appended so the operator knows which third party is involved.
  */
 const MCP_TOOL_DESCRIPTIONS: Record<string, string> = {
   // agent-config — every agent's self-service surface (#1163, #1215)
@@ -65,160 +54,225 @@ const MCP_TOOL_DESCRIPTIONS: Record<string, string> = {
   "mcp__hindsight__recall": "Recall relevant memories",
   "mcp__hindsight__retain": "Retain a memory",
   "mcp__hindsight__reflect": "Reflect across its memory bank",
+  // external integrations — common verbs (get a "(Server)" tag)
+  "mcp__perplexity__search": "Search the web",
+  "mcp__perplexity__ask": "Ask the web",
 };
 
+const INTERNAL_MCP_SERVERS = new Set([
+  "agent-config",
+  "hostd",
+  "hindsight",
+  "switchroom-telegram",
+]);
+
+/**
+ * Build the multi-line card body for an approval prompt.
+ *
+ *   🔐 <b>Gymbro</b> wants to edit: supplement-log.md
+ *   why: <i>logging today's lifts</i>
+ *
+ * Output is HTML-escaped for `parse_mode: 'HTML'`. The agent name is
+ * capitalized for the sentence; dropped (with "wants to") when null —
+ * the bridge client can be anonymous during early-boot edge cases.
+ */
+export function formatPermissionCardBody(opts: {
+  toolName: string;
+  inputPreview: string | undefined;
+  description: string | undefined;
+  agentName: string | null;
+}): string {
+  const action = naturalAction(opts.toolName, opts.inputPreview);
+  const lines: string[] = [];
+
+  if (opts.agentName && opts.agentName.length > 0) {
+    lines.push(
+      `🔐 <b>${escapeTgHtml(capFirst(opts.agentName))}</b> wants to ${escapeTgHtml(action)}`,
+    );
+  } else {
+    lines.push(`🔐 ${escapeTgHtml(capFirst(action))}`);
+  }
+
+  const rawWhy = (opts.description ?? "").replace(/\s+/g, " ").trim();
+  const truncatedWhy =
+    rawWhy.length > DESCRIPTION_LINE_MAX
+      ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "…"
+      : rawWhy;
+  lines.push(
+    truncatedWhy.length > 0
+      ? `why: <i>${escapeTgHtml(truncatedWhy)}</i>`
+      : `why: <i>not provided</i>`,
+  );
+
+  return lines.join("\n");
+}
+
 /**
- * Build a title fragment for a permission prompt. Returns the toolName
- * for any tool we don't recognise — the helper is intentionally
- * conservative: better to keep the bare name than render gibberish from
- * a malformed input_preview.
+ * The natural-language action for a tool call — the part that reads
+ * after "wants to". No tool identifiers, no scope.
  */
-export function summarizeToolForTitle(
+export function naturalAction(
   toolName: string,
   inputPreview: string | undefined,
 ): string {
-  // MCP tools: `mcp__<server>__<verb>`. Prefer a curated human
-  // description (so the card reads "Read its own merged config"
-  // instead of "mcp__agent-config__config_get"). Fall through to a
-  // generic `<server>: <verb-with-spaces>` shape for unknown MCP
-  // tools and finally to the raw name when even that fails. When
-  // we have an input preview, append the first arg-value pair so
-  // the operator sees what's being requested without expanding —
-  // e.g. `Read its own merged config (key: coolify/api-token)`
-  // rather than just `Read its own merged config`. (#1790)
-  if (toolName.startsWith("mcp__")) {
-    const curated = MCP_TOOL_DESCRIPTIONS[toolName];
-    const base = curated
-      ? curated
-      : (() => {
-          const parts = toolName.split("__");
-          if (parts.length >= 3) {
-            const server = parts[1]!;
-            const verb = parts.slice(2).join("__").replace(/_/g, " ");
-            return `${server}: ${verb}`;
-          }
-          return toolName;
-        })();
-    const argHint = firstScalarArgHint(parseInput(inputPreview));
-    return argHint ? `${base} (${argHint})` : base;
-  }
-
   const input = parseInput(inputPreview);
-  if (!input) return toolName;
+
+  if (toolName.startsWith("mcp__")) return naturalMcpAction(toolName, input);
 
   switch (toolName) {
-    case "Skill": {
-      // Claude Code's Skill tool input shape has shifted across versions
-      // and skill flavours. Read defensively from every known field
-      // before falling back. The skill name is the most identifying
-      // field of the prompt; never drop it silently.
-      //
-      // (#1790) Final fallback added: when no skill-name key matches,
-      // try `command` (some Skill variants pass the invocation under
-      // that key), then the first scalar arg-value pair. Pre-fix the
-      // default returned a bare `Skill` with zero context — operators
-      // saw "🔐 Permission: Skill" with no way to tell what was being
-      // asked without tapping See more.
-      const skill =
-        readString(input, "skill") ??
-        readString(input, "skill_name") ??
-        readString(input, "skillName") ??
-        readString(input, "name") ??
-        skillBasenameFromPath(input);
-      if (skill) return `${toolName} (${skill})`;
-      const command = readString(input, "command");
-      if (command) return `${toolName}: ${truncate(command, COMMAND_TITLE_MAX)}`;
-      const argHint = firstScalarArgHint(input);
-      return argHint ? `${toolName} (${argHint})` : toolName;
-    }
-    case "Bash": {
-      const command = readString(input, "command");
-      return command ? `${toolName}: ${truncate(command, COMMAND_TITLE_MAX)}` : toolName;
-    }
-    case "Read":
     case "Edit":
-    case "Write":
     case "MultiEdit":
     case "NotebookEdit": {
-      const filePath = readString(input, "file_path") ?? readString(input, "notebook_path");
-      return filePath ? `${toolName}: ${truncate(basename(filePath), PATH_TITLE_MAX)}` : toolName;
+      const f = fileBase(input);
+      return f ? `edit: ${f}` : "edit files";
+    }
+    case "Write": {
+      const f = fileBase(input);
+      return f ? `write: ${f}` : "write files";
+    }
+    case "Read": {
+      const f = fileBase(input);
+      return f ? `read: ${f}` : "read files";
+    }
+    case "Bash": {
+      const c = input ? readString(input, "command") : null;
+      return c ? `run: ${truncate(c, COMMAND_TITLE_MAX)}` : "run shell commands";
+    }
+    case "Skill": {
+      const s = input ? resolveSkillName(input) : null;
+      return s ? `use the ${s} skill` : "use a skill";
     }
     case "Glob":
     case "Grep": {
-      const pattern = readString(input, "pattern");
-      return pattern ? `${toolName}: ${truncate(pattern, COMMAND_TITLE_MAX)}` : toolName;
+      const p = input ? readString(input, "pattern") : null;
+      return p ? `search files for: ${truncate(p, COMMAND_TITLE_MAX)}` : "search files";
     }
-    case "WebFetch":
     case "WebSearch": {
-      const query = readString(input, "url") ?? readString(input, "query");
-      return query ? `${toolName}: ${truncate(query, COMMAND_TITLE_MAX)}` : toolName;
+      const q = input ? readString(input, "query") : null;
+      return q ? `search the web for: ${truncate(q, COMMAND_TITLE_MAX)}` : "search the web";
+    }
+    case "WebFetch": {
+      const u = input ? readString(input, "url") : null;
+      return u ? `fetch a web page: ${truncate(u, COMMAND_TITLE_MAX)}` : "fetch a web page";
     }
+    case "Task":
+    case "Agent":
+      return "dispatch a sub-agent";
+    case "TodoWrite":
+      return "update its task list";
+    case "ExitPlanMode":
+      return "exit plan mode";
     default:
-      return toolName;
+      return `use ${toolName}`;
+  }
+}
+
+function naturalMcpAction(
+  toolName: string,
+  input: Record<string, unknown> | null,
+): string {
+  void input;
+  const parts = toolName.split("__");
+  const server = parts.length >= 2 ? parts[1]! : "";
+  const curated = MCP_TOOL_DESCRIPTIONS[toolName];
+  if (curated) {
+    const phrase = lowerFirst(curated);
+    return INTERNAL_MCP_SERVERS.has(server)
+      ? phrase
+      : `${phrase} (${prettyMcpServer(server)})`;
   }
+  if (parts.length >= 3) {
+    const verb = parts.slice(2).join("__").replace(/_/g, " ");
+    return INTERNAL_MCP_SERVERS.has(server)
+      ? verb
+      : `${verb} (${prettyMcpServer(server)})`;
+  }
+  return `use ${toolName}`;
 }
 
 /**
- * Build the multi-line collapsed body of an approval card (#1790).
- *
- * Pre-fix the card was a single line — `🔐 Permission: <title>` —
- * and the agent's stated `description` plus the input preview only
- * surfaced when the operator tapped "See more". For skill / generic
- * tool prompts the title alone (e.g. `Skill (mail)`) is rarely
- * enough to approve at a glance; the operator needs to see *why*
- * before they tap Allow / Deny.
- *
- * Layout mirrors the `vault_request_access` card (the gold standard):
+ * Confirmation phrase describing a grant that just landed, derived from
+ * the *scope option the operator chose* — so an always-allow's breadth
+ * is legible after the fact. Slots in after "<Agent> can now …":
  *
- *   🔐 <agent> · <tool summary>
- *   why: <description-or-"not provided">
- *
- * The agent line is dropped when `agentName` is null (the
- * gateway's bridge client may be anonymous during early-boot edge
- * cases — better to render the title than a misleading blank).
- *
- * Output is HTML-escaped and intended for `parse_mode: 'HTML'`
- * via Telegram's Bot API.
+ *   "edit any file" / "edit supplement-log.md" / "run npm commands" /
+ *   "use the mail skill" / "use any Perplexity tool"
  */
-export function formatPermissionCardBody(opts: {
-  toolName: string;
-  inputPreview: string | undefined;
-  description: string | undefined;
-  agentName: string | null;
-}): string {
-  const summary = summarizeToolForTitle(opts.toolName, opts.inputPreview);
-  const lines: string[] = [];
+export function describeGrant(
+  toolName: string,
+  inputPreview: string | undefined,
+  option: ScopeOption,
+): string {
+  const rule = option.rule;
 
-  const agentBit = opts.agentName && opts.agentName.length > 0
-    ? `<b>${escapeTgHtml(opts.agentName)}</b> · `
-    : "";
-  lines.push(`🔐 ${agentBit}${escapeTgHtml(summary)}`);
+  // MCP wildcard → "use any <Server> tool".
+  if (rule.endsWith("__*") && rule.startsWith("mcp__")) {
+    const server = rule.split("__")[1] ?? "";
+    return `use any ${prettyMcpServer(server)} tool`;
+  }
 
-  // The agent's stated reason. Always render the line — when the
-  // agent omitted a `description`, render an explicit
-  // `why: <i>not provided</i>` rather than skip silently, so the
-  // missing-rationale is visible as an agent-side failure (matches
-  // the vault card's #1790 treatment of an omitted `reason`).
-  const rawWhy = (opts.description ?? "").replace(/\s+/g, " ").trim();
-  const truncatedWhy =
-    rawWhy.length > DESCRIPTION_LINE_MAX
-      ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "…"
-      : rawWhy;
-  if (truncatedWhy.length > 0) {
-    lines.push(`why: <i>${escapeTgHtml(truncatedWhy)}</i>`);
-  } else {
-    lines.push(`why: <i>not provided</i>`);
+  const scoped = /^([A-Za-z]+)\((.+)\)$/.exec(rule);
+  if (scoped) {
+    const t = scoped[1]!;
+    const arg = scoped[2]!;
+    if (t === "Skill") return `use the ${arg} skill`;
+    if (t === "Bash") {
+      const m = /^([^:]+):\*$/.exec(arg);
+      return m ? `run ${m[1]} commands` : "run that command";
+    }
+    if (t === "Edit" || t === "MultiEdit" || t === "NotebookEdit")
+      return `edit ${basename(arg)}`;
+    if (t === "Write") return `write ${basename(arg)}`;
+    if (t === "Read") return `read ${basename(arg)}`;
+    return naturalAction(toolName, inputPreview);
   }
 
-  return lines.join("\n");
+  // Bare tool name — the broad, whole-category grants.
+  switch (rule) {
+    case "Edit":
+    case "MultiEdit":
+    case "NotebookEdit":
+      return "edit any file";
+    case "Write":
+      return "write any file";
+    case "Read":
+      return "read any file";
+    case "Bash":
+      return "run any command";
+    case "Skill":
+      return "use any skill";
+    default:
+      // Exact MCP tool or a broad-only built-in — fall back to the
+      // request's natural action.
+      return naturalAction(toolName, inputPreview);
+  }
 }
 
-/**
- * Minimal HTML escape for Telegram `parse_mode=HTML`. Mirrors
- * `escapeHtmlForTg` in gateway.ts; duplicated here to keep
- * permission-title.ts free of a gateway import (the file is
- * referenced by both server.ts and gateway.ts).
- */
+function resolveSkillName(input: Record<string, unknown>): string | null {
+  return (
+    readString(input, "skill") ??
+    readString(input, "skill_name") ??
+    readString(input, "skillName") ??
+    readString(input, "name") ??
+    skillBasenameFromPath(input)
+  );
+}
+
+function fileBase(input: Record<string, unknown> | null): string | null {
+  if (!input) return null;
+  const p = readString(input, "file_path") ?? readString(input, "notebook_path");
+  return p ? basename(p) : null;
+}
+
+function lowerFirst(text: string): string {
+  return text.length > 0 ? text.charAt(0).toLowerCase() + text.slice(1) : text;
+}
+
+function capFirst(text: string): string {
+  return text.length > 0 ? text.charAt(0).toUpperCase() + text.slice(1) : text;
+}
+
+/** Minimal HTML escape for Telegram `parse_mode=HTML`. */
 function escapeTgHtml(text: string): string {
   return text
     .replace(/&/g, "&amp;")
@@ -226,40 +280,6 @@ function escapeTgHtml(text: string): string {
     .replace(/>/g, "&gt;");
 }
 
-/**
- * Return a `key: value` hint for the first scalar (string / number /
- * boolean) arg in the input preview. Used as a last-ditch context
- * line on uncurated MCP tools and Skill calls whose canonical
- * skill-name fields are all missing.
- *
- * Skips obviously-routing keys (`chat_id`, `message_thread_id`,
- * `request_id`) that aren't useful to a human operator deciding
- * whether to approve. Returns `null` when nothing scalar remains.
- */
-function firstScalarArgHint(
-  input: Record<string, unknown> | null,
-): string | null {
-  if (!input) return null;
-  const SKIP = new Set([
-    "chat_id",
-    "chatId",
-    "message_thread_id",
-    "messageThreadId",
-    "request_id",
-    "requestId",
-  ]);
-  for (const [key, value] of Object.entries(input)) {
-    if (SKIP.has(key)) continue;
-    if (typeof value === "string" && value.length > 0) {
-      return `${key}: ${truncate(value, INPUT_VALUE_MAX)}`;
-    }
-    if (typeof value === "number" || typeof value === "boolean") {
-      return `${key}: ${String(value)}`;
-    }
-  }
-  return null;
-}
-
 function parseInput(raw: string | undefined): Record<string, unknown> | null {
   if (!raw || typeof raw !== "string") return null;
   const trimmed = raw.trim();
@@ -280,21 +300,13 @@ function readString(input: Record<string, unknown>, key: string): string | null
   return typeof value === "string" && value.length > 0 ? value : null;
 }
 
-/**
- * Some Skill tool variants pass the skill as a directory path (e.g.
- * `skills/mail/SKILL.md` or `~/.switchroom/skills/mail`). Lift the
- * skill name out of the path so the popup still says `Skill (mail)`
- * instead of dumping the full path or bare `Skill`.
- */
 function skillBasenameFromPath(input: Record<string, unknown>): string | null {
   const path = readString(input, "path") ?? readString(input, "skill_path");
   if (!path) return null;
-  // Strip a trailing /SKILL.md or filename so we land on the directory
-  // basename — that's the canonical skill name in switchroom's layout.
   const trimmed = path.replace(/\/SKILL\.md$/i, "").replace(/\/$/, "");
   const lastSlash = trimmed.lastIndexOf("/");
-  const basename = lastSlash >= 0 ? trimmed.slice(lastSlash + 1) : trimmed;
-  return basename.length > 0 ? basename : null;
+  const base = lastSlash >= 0 ? trimmed.slice(lastSlash + 1) : trimmed;
+  return base.length > 0 ? base : null;
 }
 
 function truncate(text: string, max: number): string {