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

package/src/modules/tool-manuals/tool-manuals.contract.ts

@@ -20,6 +20,16 @@ import type { CallTemplate } from '@utcp/sdk';
 /** The external KB manual's name — shared by `/agent/all-tools` and the MCP proxy. */
 export const EXTERNAL_KB_MANUAL_NAME = 'KNOWLEDGE_BASE';
 
+/**
+ * How many embedded tools a manual may advertise on the tool page. A `.tool` is
+ * author-written, so its `tools` array is unbounded input; the page renders one
+ * bullet per entry, and a thousand of them is a broken page, not a useful one.
+ * On the contract, not the service: the skills module reads it to know when a
+ * detail's capability list may be incomplete, and must not pull the service's
+ * UTCP plugins in to learn a number.
+ */
+export const MAX_CAPABILITIES = 100;
+
 export type ToolManualType = 'inline' | 'http' | 'mcp';
 
 /** How a tool variable's secret is provisioned. */
@@ -174,6 +184,21 @@ export interface ToolManualDescriptorBase {
   /** Repo-root-relative path of the `.tool` file (e.g. `Plugins/Everyone/weather.tool`). */
   path: string;
   type: ToolManualType;
+  /**
+   * A digest of the SOURCE this descriptor was parsed from — the `.tool`
+   * file's bytes, or the `mcp.json` (plus its `plugin.json`) the server entry
+   * came out of. Stamped by the scan, before any network decoration touches
+   * the descriptor, so it moves when and only when the author's file moved.
+   *
+   * It exists for {@link IToolManualService.catalogFingerprints}: a manual can
+   * change everything about what it CALLS — its `url`, its `headers`, an
+   * inline manual's embedded tool list — while its name, path, type and
+   * description stay exactly as they were, and a fingerprint built from those
+   * alone would report no change to a client whose registered copy is now
+   * wrong. INTERNAL: never on {@link ToolManualSummary}, which is serialized
+   * to the browser.
+   */
+  sourceRevision?: string;
   /**
    * Optional one-line prose from the frontmatter, for humans browsing the
    * catalog. PURELY COSMETIC — a malformed value is ignored rather than
@@ -263,6 +288,39 @@ export interface ToolManualSummary {
   // The server reads probe config through `IToolManualService.probeTargetFor`.
 }
 
+/**
+ * A `.tool` file the scan REFUSED — reported instead of silently dropped.
+ *
+ * One unparseable manual is a finding about that file, never an outage for the
+ * catalog: every other manual is listed and callable, and the refused one comes
+ * back here so the listing can say which file and why. Nothing is cached about
+ * it beyond the scan's own TTL, so fixing (or deleting) the file restores it on
+ * the next listing — no reconnect, no restart.
+ *
+ * `reason` is the validation message with its LOCATION where the parser gave
+ * one (`line N, column M` for a YAML fault, the field name for a schema one),
+ * scrubbed of anything that could be a credential — see `describeManualFault`.
+ * A `.tool` is knowledge-base content an author may have pasted a literal token
+ * into, and this string reaches an agent transcript, a browser and a log.
+ */
+export interface InvalidToolManual {
+  /** KB-relative path of the refused file, spelled as the catalog spells a manual's `path`. */
+  path: string;
+  /** Why it was refused: the validation message + location, with no credential values. */
+  reason: string;
+}
+
+/**
+ * What one caller may see of the catalog: the manuals that parsed, and the
+ * files the scan refused. Produced together by
+ * {@link IToolManualService.listAccessibleCatalog} — see there for why the two
+ * halves are never fetched apart.
+ */
+export interface AccessibleCatalog {
+  tools: ToolManualSummary[];
+  invalid: InvalidToolManual[];
+}
+
 /** One thing an `inline` manual's embedded tool list says the assistant can do. */
 export interface ToolCapability {
   name: string;
@@ -289,6 +347,25 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
 export interface IToolManualService {
   /** The `.tool` manuals the user can read, as summaries. */
   listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
+  /**
+   * BOTH halves of what this caller may see — the manuals that parsed and the
+   * files the scan refused — from ONE scan and ONE access pass.
+   *
+   * One method rather than a `listAccessible` + `listInvalid` pair, because the
+   * two halves are one answer and asking for them separately is a way to get it
+   * wrong twice: on a cold cache two calls are two disk walks and two MCP
+   * discovery passes, and if a `.tool` is written between them the response
+   * describes two different snapshots — a tool that is in neither half, or in
+   * both. Every surface that reports refusals wants both, so both is what there
+   * is to ask for.
+   *
+   * `invalid` is access-filtered for the same reason the listing is: a path is
+   * a fact about the knowledge base, and a caller who may not read the file may
+   * not learn it exists. The refused file's own frontmatter verbs are
+   * unparseable by definition, so the verdict comes from its folder's
+   * `access.md` chain — default-deny, as everywhere else.
+   */
+  listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog>;
   /**
    * One readable `.tool` by slug, with its description + capabilities, for the
    * browser tool page. `null` when no such slug exists OR the caller can't read
@@ -297,6 +374,19 @@ export interface IToolManualService {
    */
   getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
 
+  /**
+   * One line per manual the caller can read, each carrying the manual's
+   * identity AND a digest of the file it was parsed from — the input the
+   * catalog fingerprint (`GET /api/agent/catalog-revision`) is built out of.
+   *
+   * Its own accessor rather than a projection of {@link listAccessible},
+   * because the two answer different questions. A summary is what a person
+   * browsing the catalog sees; this is whether a registered copy of the
+   * catalog is still correct, which a change to a manual's `url` or an inline
+   * manual's embedded tools breaks without touching anything a summary shows.
+   * Opaque to callers: only equality is ever asked of these lines.
+   */
+  catalogFingerprints(userEmail: string): Promise<string[]>;
   /**
    * Every manual in the catalog, UNFILTERED by access — the mirror of
    * `skillService.listSkills(undefined)`. For caller-INDEPENDENT counting only
@@ -321,6 +411,18 @@ export interface IToolManualService {
    * `slug` is what addresses the manual on the variable-resolution route.
    */
   listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]>;
+  /**
+   * Tools declared on `branch` whose namespace the default-branch catalog does
+   * not serve yet, filtered to what the caller can read there. The catalog is
+   * built from the default branch only, so a server an agent declares on its
+   * draft is invisible to every tool surface until the draft is merged — this
+   * is how the agent is told where its declaration lives. `[]` for the default
+   * branch itself, or a branch with no workspace.
+   */
+  listDeclaredOnlyOnBranch(
+    userEmail: string,
+    branch: string,
+  ): Promise<{ name: string; path: string; type: ToolManualType }[]>;
   /** The embedded UTCP manual for an inline `.tool` (served at `/api/tools/:slug/manual`). */
   resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null>;
   /** Validate a draft `.tool` file's content for the renderer preview. */
@@ -372,3 +474,66 @@ export interface IToolManualService {
   /** Drop the cached catalog (call after a merge to the default branch). */
   invalidate(): void;
 }
+
+/**
+ * A tool that exists ONLY on an open change request's branch — proposed, not
+ * released. The mirror of `PendingSkill`, and deliberately NOT a
+ * {@link ToolManualSummary}: the catalog is what agents register and call, and
+ * a tool nobody has approved must never become callable just because it became
+ * visible. This is a review surface only.
+ *
+ * Who may see one is narrower than who may see the catalog: its author, and
+ * whoever could approve it. See `shared/pending-proposals.ts` for why that
+ * predicate is the access tree's answer rather than a plugin-admin check
+ * spelled out again here.
+ */
+export interface PendingTool {
+  /**
+   * The route-safe id this tool would be served under once released — the
+   * resolved UTCP manual name, exactly what the catalog puts on a
+   * {@link ToolManualSummary}. NOT the file name: a `.tool` that declares its
+   * own `id`, or one whose filename is not route-safe, must still line up with
+   * the card the next load replaces it with.
+   *
+   * Unique among released tools, because the catalog refuses a namespace
+   * collision — but NOT yet unique among proposals, which is the price of
+   * nothing having been approved: two open requests may each propose the name,
+   * and until one merges neither has claimed it. A list rendering these keys on
+   * the slug alone must compose it with {@link PendingTool.path} and
+   * {@link PendingTool.changeRequestNumber}.
+   */
+  slug: string;
+  /** The UTCP manual name the declaration would take once released. */
+  name: string;
+  /**
+   * Repo-root-relative path of the DECLARATION — the `.tool` file, or the
+   * plugin's `mcp.json`. What the library files the card under, and what tells
+   * a reader which of the two kinds of tool this is.
+   */
+  path: string;
+  type: ToolManualType;
+  /** The declared one-line prose, when there is a usable one. */
+  description?: string;
+  /**
+   * The plugin folder the declaration targets, or `null` for a `.tool` that
+   * sits directly under the plugins root and so targets none.
+   */
+  plugin: string | null;
+  /** The open change request that would release it. */
+  changeRequestNumber: number;
+  branch: string;
+  /** Display name of whoever opened the request (person or agent). */
+  authorName: string;
+  createdAt: string;
+  /** True when the caller opened the request themselves. */
+  isAuthor: boolean;
+}
+
+export interface IPendingToolService {
+  /**
+   * Tools awaiting approval that `userEmail` is entitled to see — the ones they
+   * proposed, and the ones they could approve. Never throws: a review surface
+   * failing must not take the library down with it.
+   */
+  listPendingTools(userEmail: string): Promise<PendingTool[]>;
+}

package/src/modules/tool-manuals/tool-manuals.routes.ts

@@ -1,18 +1,25 @@
 import express, { type Request, type RequestHandler } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('tool-manuals');
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import AdmZip from 'adm-zip';
 import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { isAbsence, type IFsProbe, type ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IPluginIndexService } from '../plugins/plugins.contract.js';
 import '@utcp/http'; // side effect: register the 'http' call-template type
 import { CallTemplateSerializer, type CallTemplate } from '@utcp/sdk';
-import { type IToolManualService, EXTERNAL_KB_MANUAL_NAME } from './tool-manuals.contract.js';
+import { type IPendingToolService, type IToolManualService, EXTERNAL_KB_MANUAL_NAME } from './tool-manuals.contract.js';
 import { McpServerEditError, type McpServerEditService, type McpServerWrite } from './mcp-server-edit.service.js';
+import { ToolDeleteError, type ToolDeleteService } from './tool-delete.service.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
 import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
+import { hasGitInternalsSegment } from '../../shared/git-internals.js';
 
 /** Resolve a connection-key/internal-token user id to its email (per-caller ACL). */
 export type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
@@ -44,7 +51,19 @@ export function createToolManualsAgentRoutes(
   toolManualService: IToolManualService,
   manualAuth: RequestHandler,
   resolveUserEmail: ResolveUserEmail,
-  archiveDeps?: { workspaceService: WorkspaceService; accessControl: IAccessControl; kbDirName: string },
+  archiveDeps?: {
+    workspaceService: WorkspaceService;
+    accessControl: IAccessControl;
+    kbDirName: string;
+    disk: ITreeWalker & IFsProbe;
+    /**
+     * Resolves a plugin IDENTITY (its manifest name) to its folder, so a
+     * plugin nested below the root — `Plugins/departments/eng/ado` — is
+     * archived by the one name every client knows it by. Without it only a
+     * folder directly under the root can be named.
+     */
+    pluginIndex?: Pick<IPluginIndexService, 'catalog'>;
+  },
 ): express.Router {
   const router = express.Router();
 
@@ -68,7 +87,7 @@ export function createToolManualsAgentRoutes(
       const manuals: CallTemplate[] = [kbManualTemplate(), ...userManuals];
       res.json({ manuals });
     } catch (err) {
-      console.error('[tool-manuals] all-tools failed:', err instanceof Error ? err.message : err);
+      log.error('all-tools failed:', { err });
       res.status(500).json({ error: 'Failed to list tools' });
     }
   });
@@ -91,11 +110,24 @@ export function createToolManualsAgentRoutes(
       if (!folder || folder === '.' || folder === '..' || /[/\\]/.test(folder)) {
         return void res.status(422).json({ error: 'Not a plugin folder name' });
       }
-      const { workspaceService, accessControl, kbDirName } = archiveDeps;
+      const { workspaceService, accessControl, kbDirName, disk, pluginIndex } = archiveDeps;
       const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
       await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
       const wsDir = await workspaceService.getWorkspacePath(wsId);
-      const pluginDir = path.join(wsDir, kbDirName, PLUGINS_DIR, folder);
+      // The name is a folder directly under the root, as it always was — or,
+      // when no such folder exists, a plugin's IDENTITY, which the index maps
+      // to its folder at any depth (`Plugins/departments/eng/ado`). Identity
+      // second, so a folder that spells a nested plugin's name keeps meaning
+      // the folder.
+      let pluginRel = `${PLUGINS_DIR}/${folder}`;
+      let pluginDir = path.join(wsDir, kbDirName, PLUGINS_DIR, folder);
+      if (pluginIndex && (await disk.lstatOrNull(pluginDir))?.isDirectory() !== true) {
+        const byIdentity = (await pluginIndex.catalog()).find((p) => p.name === folder)?.folders[0];
+        if (byIdentity) {
+          pluginRel = byIdentity;
+          pluginDir = path.join(wsDir, kbDirName, ...byIdentity.split('/'));
+        }
+      }
       // SYMLINKS ARE NOT SUPPORTED IN PLUGINS, anywhere. Access control
       // resolves rules by path, and a symlink is a second path to the same
       // content — a standing invitation for the spelling the ACL judged and
@@ -105,47 +137,37 @@ export function createToolManualsAgentRoutes(
       // guards, no read-time re-resolution — complexity that existed only to
       // support what the platform has no use for. Starting with the plugin
       // folder itself: a symlinked `Plugins/<folder>` is not a plugin.
-      // Only ENOENT is an absence; an EACCES/EIO answered with 404 would
-      // dress a real read problem up as a missing plugin (the same contract
-      // as the realpath/open probes below).
-      const folderStat = await fs.lstat(pluginDir).catch((err: NodeJS.ErrnoException) => {
-        if (err.code === 'ENOENT') return null;
-        throw err;
-      });
+      // Only absence is a 404; an EACCES/EIO answered with 404 would dress a
+      // real read problem up as a missing plugin (the same contract as the
+      // realpath/open probes below).
+      const folderStat = await disk.lstatOrNull(pluginDir);
       if (folderStat === null || !folderStat.isDirectory()) {
         return void res.status(404).json({ error: 'Not found' });
       }
       const rels: string[] = [];
-      const walk = async (dir: string, rel: string): Promise<void> => {
-        let entries;
-        try {
-          entries = await fs.readdir(dir, { withFileTypes: true });
-        } catch (err) {
-          // Only an absent directory is a non-event; anything else (EACCES,
-          // EIO) silently missing from the archive would hand the client an
-          // incomplete plugin stamped as success.
-          if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
-          throw err;
-        }
-        for (const e of entries) {
-          if (e.name === '.git') continue;
-          const childRel = rel ? `${rel}/${e.name}` : e.name;
-          // Dirent's isDirectory/isFile are both false for a symlink, so a
-          // link is never walked and never listed — but say so, once, because
-          // an author who committed one deserves to know it went nowhere.
-          if (e.isDirectory()) await walk(path.join(dir, e.name), childRel);
-          else if (e.isFile()) rels.push(childRel);
-          else if (e.isSymbolicLink()) {
-            console.warn(`[tool-manuals] archive of "${folder}": ${childRel} is a symlink — not supported in plugins, skipped.`);
-          }
-        }
-      };
-      await walk(pluginDir, '');
+      // Only an absent folder is a non-event; anything else (EACCES, EIO)
+      // silently missing from the archive would hand the client an
+      // incomplete plugin stamped as success — so a hole is the error.
+      await disk.walk(pluginDir, { skip: (e) => hasGitInternalsSegment(e.name), unreadable: 'throw' }, [
+        {
+          onFile(dir, name) {
+            rels.push(dir ? `${dir}/${name}` : name);
+          },
+          onOther(dir, e) {
+            // A link is never walked and never listed — but say so, once,
+            // because an author who committed one deserves to know it went
+            // nowhere.
+            if (!e.isSymbolicLink()) return;
+            const childRel = dir ? `${dir}/${e.name}` : e.name;
+            log.warn(`archive of "${folder}": ${childRel} is a symlink — not supported in plugins, skipped.`);
+          },
+        },
+      ]);
       if (rels.length === 0) return void res.status(404).json({ error: 'Not found' });
       const verdicts = await accessControl.canReadBatch(
         wsId,
         email,
-        rels.map((r) => `${PLUGINS_DIR}/${folder}/${r}`),
+        rels.map((r) => `${pluginRel}/${r}`),
       );
       const zip = new AdmZip();
       let included = 0;
@@ -159,14 +181,14 @@ export function createToolManualsAgentRoutes(
       // verification is a moment old, and a plugin deleted since (a workspace
       // reset, a merged deletion) is an ABSENCE, the same 404 it would have
       // been a moment earlier, not an internal error.
-      const pluginRealBase = await fs.realpath(pluginDir).catch((err: NodeJS.ErrnoException) => {
-        if (err.code === 'ENOENT') return null;
+      const pluginRealBase = await fs.realpath(pluginDir).catch((err: unknown) => {
+        if (isAbsence(err)) return null;
         throw err;
       });
       if (pluginRealBase === null) return void res.status(404).json({ error: 'Not found' });
       for (const rel of rels) {
         // Fail closed, per file — only an explicit `true` verdict is included.
-        if (verdicts.get(`${PLUGINS_DIR}/${folder}/${rel}`) !== true) continue;
+        if (verdicts.get(`${pluginRel}/${rel}`) !== true) continue;
         const abs = path.join(pluginDir, ...rel.split('/'));
         // The no-symlink rule, re-checked at read time over the WHOLE path.
         // The open below guards only the final component — a PARENT directory
@@ -174,13 +196,13 @@ export function createToolManualsAgentRoutes(
         // link with the final component still a regular file. realpath
         // resolves every component, so demanding it equal the spelled path is
         // exactly "no component is a link": identity, not mere containment.
-        const realNow = await fs.realpath(abs).catch((err: NodeJS.ErrnoException) => {
-          if (err.code === 'ENOENT') return null; // deleted since the walk — an absence, not a failure
+        const realNow = await fs.realpath(abs).catch((err: unknown) => {
+          if (isAbsence(err)) return null; // deleted since the walk — an absence, not a failure
           throw err;
         });
         if (realNow === null || realNow !== path.join(pluginRealBase, ...rel.split('/'))) {
           if (realNow !== null) {
-            console.warn(`[tool-manuals] archive of "${folder}": ${rel} no longer resolves to itself — skipped.`);
+            log.warn(`archive of "${folder}": ${rel} no longer resolves to itself — skipped.`);
           }
           continue;
         }
@@ -191,15 +213,15 @@ export function createToolManualsAgentRoutes(
         // O_NOFOLLOW makes a final-component symlink fail the open itself
         // where the platform defines it (Linux — production; Windows test
         // runs fall back to the realpath identity check above alone). Only an
-        // ENOENT is a skip; any other failure is a real read problem that
+        // absence is a skip; any other failure is a real read problem that
         // must surface as a 500, not ship as a silently partial archive.
         const handle = await fs
           .open(abs, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0))
           .catch((err: NodeJS.ErrnoException) => {
-            if (err.code === 'ENOENT') return null; // deleted since the walk — an absence
+            if (isAbsence(err)) return null; // deleted since the walk — an absence
             if (err.code === 'ELOOP') {
               // O_NOFOLLOW's spelling of "the final component is a symlink".
-              console.warn(`[tool-manuals] archive of "${folder}": ${rel} is a symlink — not supported in plugins, skipped.`);
+              log.warn(`archive of "${folder}": ${rel} is a symlink — not supported in plugins, skipped.`);
               return null;
             }
             throw err;
@@ -235,7 +257,7 @@ export function createToolManualsAgentRoutes(
       res.setHeader('Content-Type', 'application/zip');
       res.send(zip.toBuffer());
     } catch (err) {
-      console.error('[tool-manuals] plugin archive failed:', err instanceof Error ? err.message : err);
+      log.error('plugin archive failed:', { err });
       res.status(500).json({ error: 'Failed to archive plugin' });
     }
   });
@@ -249,7 +271,7 @@ export function createToolManualsAgentRoutes(
       if (!manual) return void res.status(404).json({ error: 'Not found' });
       res.json(manual);
     } catch (err) {
-      console.error('[tool-manuals] manual resolve failed:', err instanceof Error ? err.message : err);
+      log.error('manual resolve failed:', { err });
       res.status(500).json({ error: 'Failed to resolve manual' });
     }
   });
@@ -260,7 +282,10 @@ export function createToolManualsAgentRoutes(
 /**
  * Browser-facing tool-manual routes (mounted under the JWT auth middleware):
  *   GET  /tools           — the caller's accessible `.tool` manuals (summaries).
+ *   GET  /tools/pending   — tools proposed on an open change request, not released.
  *   POST /tools/preview    — validate a draft `.tool` for the renderer.
+ *   GET  /tools/:slug/dependents — what deleting this tool would affect.
+ *   DELETE /tools/:slug    — delete the manual (or the mcp.json server entry).
  *   GET  /tools/:slug      — one readable manual with description + capabilities
  *                            (the tool page). Registered LAST so no future
  *                            literal sibling is shadowed by the param segment;
@@ -269,9 +294,47 @@ export function createToolManualsAgentRoutes(
 export function createToolManualsBrowserRoutes(
   toolManualService: IToolManualService,
   serverEdit?: { service: McpServerEditService; getUser: (userId: string) => Promise<AuthUser | undefined> },
+  toolDelete?: { service: ToolDeleteService; getUser: (userId: string) => Promise<AuthUser | undefined> },
+  pendingTools?: IPendingToolService,
 ): express.Router {
   const router = express.Router();
 
+  /**
+   * What depends on a tool, and the delete itself — the owner's verb, gated in
+   * the service on the same `canOwner` verdict the plugin delete enforces.
+   *
+   * Both answer 404 for a tool the caller cannot read (indistinguishable from
+   * an unknown slug, as everywhere in this file) and 403 for one they can read
+   * but do not own — at that point the tool's existence is not a secret from
+   * them, and "you are not an owner" is the only useful thing to say.
+   */
+  router.get('/tools/:slug/dependents', async (req, res) => {
+    if (!toolDelete) return void res.status(404).json({ error: 'Not available' });
+    const email = req.userEmail;
+    if (!email) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      res.json(await toolDelete.service.dependents(email, String(req.params.slug)));
+    } catch (err) {
+      if (err instanceof ToolDeleteError) return void res.status(err.status).json({ error: err.message });
+      log.error('dependents failed:', { err });
+      res.status(500).json({ error: 'Failed to read what depends on this tool' });
+    }
+  });
+
+  router.delete('/tools/:slug', async (req, res) => {
+    if (!toolDelete) return void res.status(404).json({ error: 'Not available' });
+    if (!req.userId) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      const user = await toolDelete.getUser(req.userId);
+      if (!user) return void res.status(401).json({ error: 'Not authenticated' });
+      res.json(await toolDelete.service.deleteTool(user, String(req.params.slug)));
+    } catch (err) {
+      if (err instanceof ToolDeleteError) return void res.status(err.status).json({ error: err.message });
+      log.error('tool delete failed:', { err });
+      res.status(500).json({ error: 'Failed to delete the tool' });
+    }
+  });
+
   /**
    * Server-scoped read/write of one MCP server — the tool page's edit form.
    * One server's truth spans mcp.json AND plugin.json's extensions block; a
@@ -288,7 +351,7 @@ export function createToolManualsBrowserRoutes(
       if (!view) return void res.status(404).json({ error: 'Not found' });
       res.json(view);
     } catch (err) {
-      console.error('[tool-manuals] server read failed:', err instanceof Error ? err.message : err);
+      log.error('server read failed:', { err });
       res.status(500).json({ error: 'Failed to read the server' });
     }
   });
@@ -309,7 +372,7 @@ export function createToolManualsBrowserRoutes(
       if (err instanceof McpServerEditError) {
         return void res.status(err.status).json({ error: err.message });
       }
-      console.error('[tool-manuals] server write failed:', err instanceof Error ? err.message : err);
+      log.error('server write failed:', { err });
       res.status(500).json({ error: 'Failed to save the server' });
     }
   });
@@ -318,13 +381,34 @@ export function createToolManualsBrowserRoutes(
     const email = req.userEmail;
     if (!email) return void res.status(401).json({ error: 'Not authenticated' });
     try {
-      res.json({ tools: await toolManualService.listAccessible(email) });
+      // `invalid` rides along with the catalog, out of ONE scan: a `.tool` the
+      // scan refused is the ONE reason a tool can be missing here, and a
+      // listing that dropped it in silence is indistinguishable from a
+      // workspace that never had it. Both halves therefore describe the same
+      // snapshot — a file cannot be absent from both because it was written
+      // between two reads.
+      res.json(await toolManualService.listAccessibleCatalog(email));
     } catch (err) {
-      console.error('[tool-manuals] list failed:', err);
+      log.error('list failed:', { err });
       res.status(500).json({ error: 'Internal error' });
     }
   });
 
+  /**
+   * BEFORE `/tools/:slug`, and it has to stay there: Express matches in
+   * declaration order, so the parameterised route would otherwise swallow
+   * `pending` and answer "no such tool".
+   *
+   * Optional dependency so a host that composes its own service set gets an
+   * empty review shelf rather than a 404 the frontend has to special-case —
+   * the same shape `GET /skills/pending` has.
+   */
+  router.get('/tools/pending', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) return void res.status(401).json({ error: 'Not authenticated' });
+    res.json({ tools: pendingTools ? await pendingTools.listPendingTools(email) : [] });
+  });
+
   router.post('/tools/preview', async (req, res) => {
     const email = req.userEmail;
     if (!email) return void res.status(401).json({ error: 'Not authenticated' });
@@ -344,7 +428,7 @@ export function createToolManualsBrowserRoutes(
       if (!tool) return void res.status(404).json({ error: 'Not found' });
       res.json({ tool });
     } catch (err) {
-      console.error('[tool-manuals] detail failed:', err);
+      log.error('detail failed:', { err });
       res.status(500).json({ error: 'Failed to load tool' });
     }
   });