@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/skills/allowed-tools-check.ts

@@ -0,0 +1,352 @@
+import { PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import type { IToolRegistry } from '../tool-registry/tool.contract.js';
+import {
+  EXTERNAL_KB_MANUAL_NAME,
+  MAX_CAPABILITIES,
+  type IToolManualService,
+} from '../tool-manuals/tool-manuals.contract.js';
+import { parseSkillFrontmatter } from './skills.service.js';
+
+const log = logger('skills');
+
+/**
+ * Checks a skill's `allowed-tools` against the tools the platform actually
+ * serves, and says so when an entry names one that does not exist.
+ *
+ * A WARNING, never a refusal. The list is shared with the client: a skill
+ * names the agent's own tools there too (`Bash`, `Read`, `Bash(git:*)`), and
+ * the platform cannot know those. So an entry is only checked when it LOOKS
+ * like a platform tool:
+ *
+ *  - a manual-qualified name, `hubspot.search` (the UTCP namespace);
+ *  - an MCP-style name for this server, `mcp__hexis__<tool>` — `<tool>` being
+ *    a core tool (`read_file`) or a manual's tool as the proxy names it
+ *    (`hubspot_search`);
+ *  - a bare lowercase name: a manual (`hubspot`), a core tool, or `<manual>_<tool>`.
+ *
+ * Everything else is the client's: names starting with a capital (Claude
+ * Code's `Bash`, `WebFetch`, …), permission-rule syntax (`Bash(git:*)`),
+ * wildcards, another MCP server's `mcp__<server>__…`, and the lowercase
+ * client tools listed in {@link CLIENT_TOOL_NAMES}.
+ */
+
+/** One entry the platform could not resolve. */
+export interface AllowedToolWarning {
+  /**
+   * The `allowed-tools` entry as written, with surrounding whitespace
+   * removed — the only normalization applied. A YAML list may quote an entry
+   * with padding (`- " hubspot.search "`); the padding is not part of the
+   * name, and echoing it back would name an entry the author cannot find.
+   */
+  entry: string;
+  /** A sentence naming the entry, and the suggestion when there is one. */
+  message: string;
+  /** The closest tool name the caller can see, in the entry's own spelling. */
+  suggestion?: string;
+}
+
+/**
+ * The tools a caller can see. `tools: null` for a manual whose tools are only
+ * discovered at call time (`http`/`mcp`) — any tool under it is accepted,
+ * because nothing here can prove it absent without a network round-trip.
+ */
+export interface VisibleTools {
+  core: string[];
+  manuals: { name: string; tools: string[] | null }[];
+}
+
+/** The MCP server prefix this platform's tools carry in a client's tool list. */
+export const MCP_PREFIX = 'mcp__hexis__';
+
+/**
+ * Lowercase tool names that belong to agent CLIENTS, not the platform —
+ * capitalised ones (every Claude Code tool) are exempt by shape already.
+ * Explicit rather than clever: a name added here is never flagged.
+ */
+export const CLIENT_TOOL_NAMES: ReadonlySet<string> = new Set([
+  // Codex / OpenAI agents
+  'shell',
+  'apply_patch',
+  'update_plan',
+  'view_image',
+  'web_search',
+  'local_shell',
+  // Gemini CLI
+  'run_shell_command',
+  'read_many_files',
+  'google_web_search',
+  'web_fetch',
+  'save_memory',
+  'glob',
+  'replace',
+]);
+
+/**
+ * Whether an entry has one of the shapes the platform checks — decided from
+ * the entry alone, before any catalog is read. A list of nothing but client
+ * tools (`Bash Read Edit`) therefore costs no catalog reads, which matters
+ * because `get_skill` runs on every skill use, and the catalog behind a check
+ * is a skill listing, a manual listing and one detail read per inline manual.
+ */
+export function looksLikePlatformTool(raw: string): boolean {
+  const entry = raw.trim();
+  if (!entry || /[()*\s]/.test(entry)) return false; // permission-rule syntax or a wildcard
+  const lower = entry.toLowerCase();
+  if (lower.startsWith('mcp__')) return lower.startsWith(MCP_PREFIX); // else another MCP server's tool
+  const dot = entry.indexOf('.');
+  if (dot > 0) return /^\w+$/.test(lower.slice(0, dot)); // else not a manual name — a file, a URL, …
+  // Bare names: a capital first letter is a client tool's shape.
+  return /^[a-z][\w-]*$/.test(entry) && !CLIENT_TOOL_NAMES.has(entry);
+}
+
+/** Classify and resolve every entry; only unresolved platform-looking ones come back. */
+export function checkAllowedTools(entries: readonly string[], visible: VisibleTools): AllowedToolWarning[] {
+  const core = new Set(visible.core.map((n) => n.toLowerCase()));
+  const manuals = new Map(
+    visible.manuals.map((m) => [m.name.toLowerCase(), m.tools?.map((t) => t.toLowerCase()) ?? null]),
+  );
+  const warnings: AllowedToolWarning[] = [];
+  const seen = new Set<string>();
+  for (const raw of entries) {
+    const entry = raw.trim();
+    if (!entry || seen.has(entry)) continue;
+    seen.add(entry);
+    const warning = checkEntry(entry, core, manuals, visible);
+    if (warning) warnings.push(warning);
+  }
+  return warnings;
+}
+
+function checkEntry(
+  entry: string,
+  core: Set<string>,
+  manuals: Map<string, string[] | null>,
+  visible: VisibleTools,
+): AllowedToolWarning | null {
+  if (!looksLikePlatformTool(entry)) return null;
+  const lower = entry.toLowerCase();
+
+  if (lower.startsWith(MCP_PREFIX)) {
+    const name = lower.slice(MCP_PREFIX.length);
+    if (core.has(name) || resolvesUnderscored(name, manuals)) return null;
+    return warn(
+      entry,
+      lower,
+      [...visible.core.map((c) => MCP_PREFIX + c), ...underscoredCandidates(visible).map((c) => MCP_PREFIX + c)],
+      MCP_PREFIX.length,
+    );
+  }
+
+  const dot = entry.indexOf('.');
+  if (dot > 0) {
+    const manual = lower.slice(0, dot);
+    const tool = lower.slice(dot + 1);
+    // The core toolset's own namespace, as `call_tool_chain` spells it.
+    if (manual === EXTERNAL_KB_MANUAL_NAME.toLowerCase()) {
+      if (core.has(tool)) return null;
+      return warn(entry, lower, visible.core.map((c) => `${EXTERNAL_KB_MANUAL_NAME}.${c}`), dot + 1);
+    }
+    const tools = manuals.get(manual);
+    if (tools === null) return null;
+    if (tools === undefined) {
+      // The manual itself is unknown, so the typo may be anywhere in the name.
+      return warn(
+        entry,
+        lower,
+        visible.manuals.flatMap((m) => (m.tools ? m.tools.map((t) => `${m.name}.${t}`) : [`${m.name}.${entry.slice(dot + 1)}`])),
+      );
+    }
+    if (tools.includes(tool)) return null;
+    // The manual is known: only its own tools are candidates, and only the
+    // tool part is scored.
+    const known = visible.manuals.find((m) => m.name.toLowerCase() === manual);
+    return warn(entry, lower, (known?.tools ?? []).map((t) => `${known!.name}.${t}`), dot + 1);
+  }
+
+  if (core.has(lower) || manuals.has(lower) || resolvesUnderscored(lower, manuals)) return null;
+  return warn(entry, lower, [...visible.core, ...visible.manuals.map((m) => m.name), ...underscoredCandidates(visible)]);
+}
+
+/** `<manual>_<tool>` — how the MCP proxy names a manual's tool. */
+function resolvesUnderscored(name: string, manuals: Map<string, string[] | null>): boolean {
+  for (const [manual, tools] of manuals) {
+    if (!name.startsWith(`${manual}_`)) continue;
+    const tool = name.slice(manual.length + 1);
+    // Manual names may hold underscores themselves, so keep looking on a miss.
+    if (tools === null || tools.includes(tool)) return true;
+  }
+  return false;
+}
+
+function underscoredCandidates(visible: VisibleTools): string[] {
+  return visible.manuals.flatMap((m) => (m.tools ?? []).map((t) => `${m.name}_${t}`));
+}
+
+/**
+ * @param shared How many leading characters the entry and every candidate
+ *   share (`mcp__hexis__`, `<manual>.`). They are left out of the typo
+ *   scoring: the budget is a third of the scored name, and a prefix pads it
+ *   with characters that can never be misspelt — scored whole,
+ *   `mcp__hexis__weather_forecast` was "corrected" to `mcp__hexis__write_files`.
+ *   The suggestion keeps the entry's own prefix in front of the candidate's tail.
+ */
+function warn(entry: string, normalized: string, candidates: string[], shared = 0): AllowedToolWarning {
+  const tail = closest(normalized.slice(shared), candidates.map((c) => c.slice(shared)));
+  const suggestion = tail === undefined ? undefined : entry.slice(0, shared) + tail;
+  return {
+    entry,
+    message: suggestion
+      ? `"${entry}" in allowed-tools is not a tool you can use here. Did you mean "${suggestion}"?`
+      : `"${entry}" in allowed-tools is not a tool you can use here.`,
+    ...(suggestion ? { suggestion } : {}),
+  };
+}
+
+/** The nearest candidate by edit distance, when it is near enough to be a typo. */
+export function closest(name: string, candidates: readonly string[]): string | undefined {
+  const limit = Math.max(1, Math.floor(name.length / 3));
+  let best: string | undefined;
+  let bestDistance = limit + 1;
+  for (const candidate of candidates) {
+    const d = editDistance(name, candidate.toLowerCase());
+    if (d < bestDistance) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  return best;
+}
+
+function editDistance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j]! + 1, cur[j - 1]! + 1, prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length]!;
+}
+
+/**
+ * The repo-relative path of a skill file (`Plugins/…/SKILL.md` or
+ * `Skills/…/SKILL.md`) when `workspacePath` names one, else `null`.
+ * Accepts the workspace spelling (`<kbDirName>/Plugins/…`) the save
+ * surfaces receive.
+ */
+export function skillFileRepoPath(kbDirName: string, workspacePath: string): string | null {
+  const parts = workspacePath.split('/').filter((p) => p && p !== '.');
+  if (parts[0] === kbDirName) parts.shift();
+  if (parts.length < 3 || parts[parts.length - 1] !== 'SKILL.md') return null;
+  return parts[0] === PLUGINS_DIR || parts[0] === SKILLS_DIR ? parts.join('/') : null;
+}
+
+/** What the save surfaces and `get_skill` depend on. */
+export interface IAllowedToolsChecker {
+  /** Warnings for a declared list, resolved against what `userEmail` can see. Never throws. */
+  check(userEmail: string, allowedTools: readonly string[] | undefined): Promise<AllowedToolWarning[]>;
+  /**
+   * Warnings for a file being saved: `[]` unless `workspacePath` is a skill
+   * file. Never throws — a save must not fail because a check could not run.
+   */
+  checkSave(userEmail: string, workspacePath: string, content: string): Promise<AllowedToolWarning[]>;
+  /**
+   * `checkSave` for a whole batch, reading the caller's catalog ONCE:
+   * `result[i]` is the warnings for `files[i]`. Never throws.
+   */
+  checkSaves(
+    userEmail: string,
+    files: readonly { path: string; content: string }[],
+  ): Promise<AllowedToolWarning[][]>;
+}
+
+/** Resolves "the tools a user can see" from the tool catalog and the manuals they may read. */
+export class AllowedToolsChecker implements IAllowedToolsChecker {
+  constructor(
+    private readonly registry: Pick<IToolRegistry, 'listExternal'>,
+    private readonly manuals: Pick<IToolManualService, 'listAccessible' | 'getDetail'>,
+    private readonly kbDirName: string,
+    /**
+     * The cap `getDetail` applies to a manual's capabilities. Taken from the
+     * projection itself: a copy of the number here would silently start
+     * reporting real tools missing the day the projection's cap grew.
+     */
+    private readonly maxCapabilities = MAX_CAPABILITIES,
+  ) {}
+
+  async check(userEmail: string, allowedTools: readonly string[] | undefined): Promise<AllowedToolWarning[]> {
+    return (await this.checkLists(userEmail, [allowedTools]))[0]!;
+  }
+
+  async checkSave(userEmail: string, workspacePath: string, content: string): Promise<AllowedToolWarning[]> {
+    return (await this.checkSaves(userEmail, [{ path: workspacePath, content }]))[0]!;
+  }
+
+  async checkSaves(
+    userEmail: string,
+    files: readonly { path: string; content: string }[],
+  ): Promise<AllowedToolWarning[][]> {
+    return this.checkLists(
+      userEmail,
+      files.map((f) => this.declaredTools(f.path, f.content)),
+    );
+  }
+
+  /**
+   * The `allowed-tools` a file being saved declares — `undefined` for a file
+   * that is not a skill, or whose frontmatter will not parse (a save must not
+   * fail because a check could not run).
+   */
+  private declaredTools(workspacePath: string, content: string): readonly string[] | undefined {
+    if (skillFileRepoPath(this.kbDirName, workspacePath) === null) return undefined;
+    try {
+      return parseSkillFrontmatter(content).allowedTools;
+    } catch (err) {
+      log.warn('allowed-tools check skipped', { err });
+      return undefined;
+    }
+  }
+
+  /**
+   * One catalog read for however many lists. A list with nothing the platform
+   * could have an opinion on costs nothing — and when no list has, the catalog
+   * is not read at all.
+   */
+  private async checkLists(
+    userEmail: string,
+    lists: readonly (readonly string[] | undefined)[],
+  ): Promise<AllowedToolWarning[][]> {
+    const worth = lists.map((l) => l?.some(looksLikePlatformTool) === true);
+    if (!worth.some(Boolean)) return lists.map(() => []);
+    try {
+      const visible = await this.visibleTools(userEmail);
+      return lists.map((l, i) => (worth[i] ? checkAllowedTools(l!, visible) : []));
+    } catch (err) {
+      log.warn('allowed-tools check skipped', { err });
+      return lists.map(() => []);
+    }
+  }
+
+  private async visibleTools(userEmail: string): Promise<VisibleTools> {
+    const [coreTools, summaries] = await Promise.all([
+      this.registry.listExternal({ userEmail }),
+      this.manuals.listAccessible(userEmail),
+    ]);
+    const manuals = await Promise.all(
+      summaries.map(async (m) => {
+        if (m.type !== 'inline') return { name: m.name, tools: null };
+        const detail = await this.manuals.getDetail(userEmail, m.slug);
+        const caps = detail?.capabilities ?? [];
+        // A capped list may be missing the very tool asked about.
+        if (!detail || caps.length >= this.maxCapabilities) return { name: m.name, tools: null };
+        return {
+          name: m.name,
+          tools: caps.map((c) => (c.name.startsWith(`${m.name}.`) ? c.name.slice(m.name.length + 1) : c.name)),
+        };
+      }),
+    );
+    return { core: coreTools.map((t) => t.name), manuals };
+  }
+}

package/src/modules/skills/index.ts

@@ -2,6 +2,9 @@ export { SkillService } from './skills.service.js';
 export { PendingSkillsService } from './pending-skills.service.js';
 export { registerSkillsTools } from './skills.tools.js';
 export { createSkillsRoutes } from './skills.routes.js';
+export { AllowedToolsChecker } from './allowed-tools-check.js';
+export type { IAllowedToolsChecker, AllowedToolWarning } from './allowed-tools-check.js';
+export { createSkillAccessRequestRoutes } from './skill-access-requests.routes.js';
 export type {
   ISkillService,
   IPendingSkillService,
@@ -10,4 +13,6 @@ export type {
   SkillFileContent,
   PendingSkill,
   GetSkillResult,
+  GetSkillOptions,
+  SkillHistorySource,
 } from './skills.contract.js';

package/src/modules/skills/pending-skills.service.ts

@@ -1,16 +1,14 @@
 import {
-  DEFAULT_BRANCH,
   PLUGINS_DIR,
-  type ChangeRequest,
-  type IWorkflowService,
+  SKILLS_DIR,
 } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { hashEmail } from '../../shared/hash-email.js';
 import { resolveDeclaredId } from '../../shared/frontmatter-id.js';
+import { visibleProposedFiles } from '../../shared/pending-proposals.js';
 import { isSafeSkillName, parseSkillFrontmatter } from './skills.service.js';
 import type { IPendingSkillService, ISkillService, PendingSkill } from './skills.contract.js';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
 
 const SKILL_DOC = 'SKILL.md';
 
@@ -26,14 +24,11 @@ const SKILL_DOC = 'SKILL.md';
  * rather than a widening of the catalog — an unapproved skill must never become
  * loadable just because it became visible.
  *
- * WHO MAY SEE ONE is narrower than who may see the catalog: the author, and
- * whoever could approve it. "Could approve it" is not re-stated here as a
- * plugin-admin check — it is `canWrite` on the SKILL.md the request would
- * create. The new folder carries no `access.md` of its own, so that verdict
- * inherits from the plugin folder, which IS the plugin's admin; asking the access
- * tree keeps this surface and the merge gate answering with one voice, and it
- * keeps working for skills nested in a category subfolder that carries rules of
- * its own.
+ * WHO MAY SEE ONE, and how a proposal is read at its own branch, live in
+ * `shared/pending-proposals.ts` — shared with the tool surface, which is the
+ * same shape for the same reasons. What stays here is what is specific to a
+ * skill: which touched paths are a skill of their own, and how a SKILL.md
+ * names itself.
  *
  * Everything degrades to "nothing pending" rather than throwing: this hangs off
  * the library's list load, and a review surface that cannot answer must not
@@ -48,17 +43,6 @@ export class PendingSkillsService implements IPendingSkillService {
   ) {}
 
   async listPendingSkills(userEmail: string): Promise<PendingSkill[]> {
-    const email = userEmail.trim().toLowerCase();
-    if (!email) return [];
-
-    let crs: ChangeRequest[];
-    try {
-      crs = (await this.workflow.listChangeRequests()).filter((c) => c.state === 'open');
-    } catch {
-      return [];
-    }
-    if (crs.length === 0) return [];
-
     // The released set, UNFILTERED by the caller's read access. A skill someone
     // else can read and this caller cannot is still released — counting it as
     // pending would invent a review that is not happening, and would leak the
@@ -70,51 +54,22 @@ export class PendingSkillsService implements IPendingSkillService {
       return [];
     }
 
-    const candidates = crs.flatMap((cr) =>
-      cr.touchedNodePaths
-        .filter((p) => isSkillDoc(p) && !released.has(folderOf(p)))
-        .map((p) => ({ cr, docPath: p, folder: folderOf(p) })),
+    const proposed = await visibleProposedFiles(
+      {
+        workspaceService: this.workspaceService,
+        accessControl: this.accessControl,
+        workflow: this.workflow,
+      },
+      userEmail,
+      (p) => isSkillDoc(p) && !released.has(folderOf(p)),
     );
-    if (candidates.length === 0) return [];
-
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
-    const authorHash = hashEmail(email);
-
-    // One access load for every candidate. Resolved on the DEFAULT branch —
-    // the tree as it stands is what says who owns the plugin the skill is
-    // arriving into; the branch's own copy is written by the proposer and must
-    // not get a say in who reviews them.
-    const writable = await this.accessControl
-      .canWriteBatch(
-        wsId,
-        email,
-        candidates.map((c) => c.docPath),
-      )
-      .catch(() => new Map<string, boolean>());
-
-    // The branch copies are read through the default branch's clone at
-    // `origin/<branch>`, so a proposal never needs a clone of its own. Refresh
-    // first, best-effort: a request pushed seconds ago is worth one fetch, and
-    // a failed fetch should degrade to "read what we have".
-    await this.workspaceService.ensureRemotesFetched(wsId).catch(() => undefined);
 
-    const out: PendingSkill[] = [];
-    for (const { cr, docPath, folder } of candidates) {
-      const isAuthor = !!cr.authorId && cr.authorId === authorHash;
-      // Fail closed, matching the catalog: only an explicit `true` admits a
-      // reviewer. A missing entry (the batch skipped the path, the tree could
-      // not be read) means denied, never shown.
-      if (!isAuthor && writable.get(docPath) !== true) continue;
-
-      const raw = await this.readAt(wsId, cr.branch, docPath);
-      // Nothing to describe: the request touched the path but the file is gone
-      // at its head (proposed then withdrawn within the branch), or unreadable.
-      if (raw === null) continue;
-
-      const fm = parseSkillFrontmatter(raw);
+    const out: PendingSkill[] = proposed.map(({ cr, path, content, isAuthor }) => {
+      const folder = folderOf(path);
+      const fm = parseSkillFrontmatter(content);
       const folderName = folder.split('/').pop() ?? folder;
       const declared = resolveDeclaredId(fm.frontmatter, folderName);
-      out.push({
+      return {
         name: isSafeSkillName(declared) ? declared : folderName,
         description: fm.description,
         version: fm.version,
@@ -124,26 +79,13 @@ export class PendingSkillsService implements IPendingSkillService {
         authorName: cr.appAuthor?.name ?? cr.author.name ?? 'Someone',
         createdAt: cr.createdAt,
         isAuthor,
-      });
-    }
+      };
+    });
     // Oldest first — the one that has been waiting longest is the one that
     // needs answering, and a list that reorders as requests arrive moves under
     // the pointer.
     return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
-
-  /** The file at a branch, or null when it is absent/unreadable there. */
-  private async readAt(
-    wsId: string,
-    branch: string,
-    repoRelPath: string,
-  ): Promise<string | null> {
-    try {
-      return await this.workspaceService.readFileAtRef(wsId, `origin/${branch}`, repoRelPath);
-    } catch {
-      return null;
-    }
-  }
 }
 
 /**
@@ -156,11 +98,10 @@ export class PendingSkillsService implements IPendingSkillService {
  */
 function isSkillDoc(repoRelPath: string): boolean {
   const segments = repoRelPath.split('/');
-  return (
-    segments.length >= 4 &&
-    segments[0] === PLUGINS_DIR &&
-    segments[segments.length - 1] === SKILL_DOC
-  );
+  if (segments[segments.length - 1] !== SKILL_DOC) return false;
+  // Under `Skills/` a skill may sit directly below the root: `Skills/<skill>/SKILL.md`.
+  if (segments[0] === SKILLS_DIR) return segments.length >= 3;
+  return segments.length >= 4 && segments[0] === PLUGINS_DIR;
 }
 
 /** The skill folder holding a SKILL.md. */