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

package/dist/modules/tool-manuals/tool-manuals.contract.d.ts

@@ -17,6 +17,15 @@ import type { CallTemplate } from '@utcp/sdk';
  */
 /** The external KB manual's name — shared by `/agent/all-tools` and the MCP proxy. */
 export declare 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 declare const MAX_CAPABILITIES = 100;
 export type ToolManualType = 'inline' | 'http' | 'mcp';
 /** How a tool variable's secret is provisioned. */
 export type ToolVariableScope = 'admin' | 'user';
@@ -164,6 +173,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
@@ -251,6 +275,37 @@ export interface ToolManualSummary {
     /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
     setup?: ToolManualSetup;
 }
+/**
+ * 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;
@@ -275,6 +330,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
@@ -282,6 +356,19 @@ export interface IToolManualService {
      * confirm that a tool the caller can't see exists).
      */
     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
@@ -312,6 +399,19 @@ export interface IToolManualService {
         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. */
@@ -365,4 +465,65 @@ 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[]>;
+}
 //# sourceMappingURL=tool-manuals.contract.d.ts.map

package/dist/modules/tool-manuals/tool-manuals.contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-manuals.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AAEH,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvD,mDAAmD;AACnD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,iBAAiB,CAAC;IACzB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;OAIG;IACH,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,cAAc,CAAC;IAC7C,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,GAC5B,CAAC,wBAAwB,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,GACpE,CAAC,wBAAwB,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;AAE5F,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,sDAAsD;IACtD,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,eAAe,CAAC;CAKzB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC;IAC9E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAChE;;;;;;;;;;;;;;;;;OAiBG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrE;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAE7E;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1D;;;;;;OAMG;IACH,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACnG;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;IAC1F;;;;;;;OAOG;IACH,wBAAwB,CACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAA;KAAE,EAAE,CAAC,CAAC;IACnE,4FAA4F;IAC5F,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrF,wEAAwE;IACxE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrD;;;;;;OAMG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACjF;;;;;OAKG;IACH,uBAAuB,CACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CACR;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAC9F,CAAC;IACF,0EAA0E;IAC1E,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qDAAqD;IACrD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC7D"}

package/dist/modules/tool-manuals/tool-manuals.contract.js

@@ -16,4 +16,13 @@
  */
 /** 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;
 //# sourceMappingURL=tool-manuals.contract.js.map

package/dist/modules/tool-manuals/tool-manuals.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.contract.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,gBAAgB,CAAC"}
+{"version":3,"file":"tool-manuals.contract.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,gBAAgB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC"}

package/dist/modules/tool-manuals/tool-manuals.routes.d.ts

@@ -1,9 +1,12 @@
 import express, { type RequestHandler } from 'express';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { 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';
-import { type IToolManualService } from './tool-manuals.contract.js';
+import { type IPendingToolService, type IToolManualService } from './tool-manuals.contract.js';
 import { type McpServerEditService } from './mcp-server-edit.service.js';
+import { type ToolDeleteService } from './tool-delete.service.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js';
 import '../tool-auth/tool-auth.middleware.js';
@@ -22,11 +25,22 @@ export declare function createToolManualsAgentRoutes(toolManualService: IToolMan
     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;
 /**
  * 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;
@@ -35,5 +49,8 @@ export declare function createToolManualsAgentRoutes(toolManualService: IToolMan
 export declare function createToolManualsBrowserRoutes(toolManualService: IToolManualService, serverEdit?: {
     service: McpServerEditService;
     getUser: (userId: string) => Promise<AuthUser | undefined>;
-}): express.Router;
+}, toolDelete?: {
+    service: ToolDeleteService;
+    getUser: (userId: string) => Promise<AuthUser | undefined>;
+}, pendingTools?: IPendingToolService): express.Router;
 //# sourceMappingURL=tool-manuals.routes.d.ts.map

package/dist/modules/tool-manuals/tool-manuals.routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAgB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAKrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,YAAY,CAAC;AAEpB,OAAO,EAAE,KAAK,kBAAkB,EAA2B,MAAM,4BAA4B,CAAC;AAC9F,OAAO,EAAsB,KAAK,oBAAoB,EAAuB,MAAM,8BAA8B,CAAC;AAClH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,4BAA4B,CAAC;AACpC,OAAO,sCAAsC,CAAC;AAE9C,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAgB/E;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,EAAE,cAAc,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,CAAC,EAAE;IAAE,gBAAgB,EAAE,gBAAgB,CAAC;IAAC,aAAa,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrG,OAAO,CAAC,MAAM,CAkNhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,CAAC,EAAE;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CAAE,GACzG,OAAO,CAAC,MAAM,CAiFhB"}
+{"version":3,"file":"tool-manuals.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAgB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAQrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAa,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,YAAY,CAAC;AAEpB,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAA2B,MAAM,4BAA4B,CAAC;AACxH,OAAO,EAAsB,KAAK,oBAAoB,EAAuB,MAAM,8BAA8B,CAAC;AAClH,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,4BAA4B,CAAC;AACpC,OAAO,sCAAsC,CAAC;AAG9C,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAgB/E;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,EAAE,cAAc,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,CAAC,EAAE;IACZ,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,aAAa,EAAE,cAAc,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;CACpD,GACA,OAAO,CAAC,MAAM,CAqNhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,CAAC,EAAE;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CAAE,EAC1G,UAAU,CAAC,EAAE;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CAAE,EACvG,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,MAAM,CA0IhB"}

package/dist/modules/tool-manuals/tool-manuals.routes.js

@@ -1,15 +1,20 @@
 import express 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 { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { isAbsence } from '../../shared/fs.contract.js';
 import '@utcp/http'; // side effect: register the 'http' call-template type
 import { CallTemplateSerializer } from '@utcp/sdk';
 import { EXTERNAL_KB_MANUAL_NAME } from './tool-manuals.contract.js';
 import { McpServerEditError } from './mcp-server-edit.service.js';
+import { ToolDeleteError } from './tool-delete.service.js';
 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';
 const callTemplateSerializer = new CallTemplateSerializer();
 /** The external KB manual's discovery call-template — Bevel's own `/api/agent/utcp`. */
 function kbManualTemplate() {
@@ -55,7 +60,7 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
             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' });
         }
     });
@@ -79,11 +84,24 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
             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
@@ -93,51 +111,36 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
             // 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) => {
-                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 = [];
-            const walk = async (dir, rel) => {
-                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.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}`));
+            const verdicts = await accessControl.canReadBatch(wsId, email, rels.map((r) => `${pluginRel}/${r}`));
             const zip = new AdmZip();
             let included = 0;
             let bytes = 0;
@@ -151,7 +154,7 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
             // 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) => {
-                if (err.code === 'ENOENT')
+                if (isAbsence(err))
                     return null;
                 throw err;
             });
@@ -159,7 +162,7 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
                 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)
+                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.
@@ -169,13 +172,13 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
                 // 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) => {
-                    if (err.code === 'ENOENT')
+                    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;
                 }
@@ -186,16 +189,16 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
                 // 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) => {
-                    if (err.code === 'ENOENT')
+                    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;
@@ -236,7 +239,7 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
             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' });
         }
     });
@@ -252,7 +255,7 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
             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' });
         }
     });
@@ -261,14 +264,60 @@ export function createToolManualsAgentRoutes(toolManualService, manualAuth, reso
 /**
  * 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;
  *                            `preview` is POST-only, so it never collides.
  */
-export function createToolManualsBrowserRoutes(toolManualService, serverEdit) {
+export function createToolManualsBrowserRoutes(toolManualService, serverEdit, toolDelete, pendingTools) {
     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
@@ -289,7 +338,7 @@ export function createToolManualsBrowserRoutes(toolManualService, serverEdit) {
             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 +358,7 @@ export function createToolManualsBrowserRoutes(toolManualService, serverEdit) {
             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 +367,34 @@ export function createToolManualsBrowserRoutes(toolManualService, serverEdit) {
         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)
@@ -347,7 +417,7 @@ export function createToolManualsBrowserRoutes(toolManualService, serverEdit) {
             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' });
         }
     });