@bevel-software/platform-core-backend 0.25.2 → 0.26.0

package/src/modules/settings/deployment-settings.service.ts

@@ -7,7 +7,6 @@ import { deploymentSettings } from '../database/core-schema.js';
 import {
   DEFAULT_KB_LAYOUT,
   type KbLayout,
-  validateAgentsFileName,
   validateBranchModel,
   validateKbLayout,
   validateKbRootName,
@@ -228,14 +227,16 @@ export const CORE_SETTINGS: SettingDef[] = [
   /**
    * The KB layout: the three root folders a deployment may rename so hexis can
    * read a repository laid out by someone else (`skills/` and `plugins/` in
-   * lowercase, say), and the file name of the managed agent guide.
+   * lowercase, say). The agent guide's name is not among them any more: the
+   * guide is served by the platform as `AGENTS.md` everywhere, and a name a
+   * deployment saved for the written guide is ignored.
    * Restart-to-apply like the branch model — the names are applied once at boot
    * through `configureKbLayout` and served to the browser once by
    * `/api/config`. Each has a default, so an unset field means the default, not
-   * an unconfigured deployment. Checked as a QUARTET in `save`: the four must
+   * an unconfigured deployment. Checked as a TRIO in `save`: the three must
    * differ, and one field alone cannot see the other three.
    *
-   * NO `envVar`, on any of the four. Layout is deployment configuration that is
+   * NO `envVar`, on any of the three. Layout is deployment configuration that is
    * entered once in the app; the three that used to be environment-driven are
    * imported into their saved setting on the first boot after the upgrade
    * ({@link DeploymentSettingsService.importLegacyLayoutEnv}) so nothing
@@ -262,37 +263,6 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
     unsetMeans: DEFAULT_KB_LAYOUT.pluginsDir,
   },
-  {
-    /**
-     * The managed agent guide's file name. Its own validator says what a guide
-     * may be called; the quartet check in `plan` is what keeps it clear of the
-     * three folder names it is saved beside.
-     */
-    key: 'agentsFile',
-    section: 'knowledge-base',
-    // Judged against the default roots here; the quartet check in `plan`
-    // judges it against the roots the same save puts in effect.
-    validate: (v) => validateAgentsFileName(v, DEFAULT_KB_LAYOUT),
-    restartToApply: true,
-    unsetMeans: DEFAULT_KB_LAYOUT.agentsFile,
-  },
-  {
-    /**
-     * Whether to keep the platform's one-sentence pointer in a customer's own
-     * `AGENTS.md` — the admin's consent to the only text the platform ever adds
-     * to a file it does not own. On unless it is explicitly turned off, because
-     * a renamed guide nothing points at is a guide no coding agent will find.
-     *
-     * Restart-to-apply like the name it belongs to: the check runs once per
-     * start, in the KB startup phase.
-     */
-    key: 'agentsFileLink',
-    section: 'knowledge-base',
-    validate: (v) => (v === 'true' || v === 'false' ? null : 'Use "true" or "false".'),
-    restartToApply: true,
-    // On unless explicitly turned off — the reading `resolveAgentsFileLink` applies.
-    unsetMeans: 'true',
-  },
 
 
   /**
@@ -587,20 +557,10 @@ export class DeploymentSettingsService {
       knowledgeBaseDir: this.resolve('knowledgeBaseDir') || DEFAULT_KB_LAYOUT.knowledgeBaseDir,
       skillsDir: this.resolve('skillsDir') || DEFAULT_KB_LAYOUT.skillsDir,
       pluginsDir: this.resolve('pluginsDir') || DEFAULT_KB_LAYOUT.pluginsDir,
-      agentsFile: this.resolve('agentsFile') || DEFAULT_KB_LAYOUT.agentsFile,
+      agentsFile: DEFAULT_KB_LAYOUT.agentsFile,
     };
   }
 
-  /**
-   * Whether the platform should keep its pointer sentence in a customer-owned
-   * `AGENTS.md`. On unless the admin turned it off — an unset setting is a
-   * deployment that never saw the checkbox, and the sentence is what makes a
-   * renamed guide findable at all.
-   */
-  resolveAgentsFileLink(): boolean {
-    return this.resolve('agentsFileLink') !== 'false';
-  }
-
   /**
    * Import the retired layout environment variables into their saved settings,
    * ONCE, on a deployment that still sets them.
@@ -832,12 +792,12 @@ export class DeploymentSettingsService {
       if (problem) problems.protectedBranches = problem;
     }
 
-    // The layout quartet is the other cross-field rule: three folder names and
-    // a guide file name that must all differ. Judged on the layout this save
-    // WOULD produce, with the default standing in for anything neither written
-    // nor stored — so renaming the plugins folder to what the guide is already
-    // called is refused whichever of the two the save names.
-    const layoutKeys = ['knowledgeBaseDir', 'skillsDir', 'pluginsDir', 'agentsFile'] as const;
+    // The layout trio is the other cross-field rule: three folder names that
+    // must all differ. Judged on the layout this save WOULD produce, with the
+    // default standing in for anything neither written nor stored — so
+    // renaming one folder to what another is already called is refused
+    // whichever of the two the save names.
+    const layoutKeys = ['knowledgeBaseDir', 'skillsDir', 'pluginsDir'] as const;
     if (toWrite.some((w) => (layoutKeys as readonly string[]).includes(w.key))) {
       const effective = (key: (typeof layoutKeys)[number]) =>
         toWrite.find((w) => w.key === key)?.value || this.resolve(key) || DEFAULT_KB_LAYOUT[key];
@@ -845,7 +805,6 @@ export class DeploymentSettingsService {
         knowledgeBaseDir: effective('knowledgeBaseDir'),
         skillsDir: effective('skillsDir'),
         pluginsDir: effective('pluginsDir'),
-        agentsFile: effective('agentsFile'),
       });
       // Against the field being written — the first one in the batch — since
       // any of the three could be the one that collides.
@@ -873,7 +832,7 @@ export class DeploymentSettingsService {
           knowledgeBaseDir: effective('knowledgeBaseDir'),
           skillsDir: effective('skillsDir'),
           pluginsDir: effective('pluginsDir'),
-          agentsFile: effective('agentsFile'),
+          agentsFile: DEFAULT_KB_LAYOUT.agentsFile,
         });
       } catch (err) {
         // Against the field this save is writing — the checkout name when that

package/src/modules/settings/setup.routes.ts

@@ -64,17 +64,14 @@ const SECRET_FOR_THAT_PROVIDER =
   'Enter the application secret for that provider — the saved one is only sent to the provider it was saved for.';
 
 /**
- * The knowledge-base layout as setting keys: the three renameable roots, the
- * guide's file name, and the consent that rides with it — which the KB startup
- * phase reads through a getter, so the completing save puts it in effect along
- * with the names.
+ * The knowledge-base layout as setting keys: the three renameable roots. The
+ * guide's file name is not one of them — the settings layer sets none, so the
+ * layout it produces carries the default, `AGENTS.md`.
  */
 const LAYOUT_KEYS: readonly string[] = [
   'knowledgeBaseDir',
   'skillsDir',
   'pluginsDir',
-  'agentsFile',
-  'agentsFileLink',
 ];
 /** The branch model, as setting keys. */
 const BRANCH_KEYS: readonly string[] = ['defaultBranch', 'protectedBranches'];

package/src/modules/skills/__tests__/skills.tools.description.test.ts

@@ -0,0 +1,91 @@
+import express from 'express';
+import { describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { TOOL_DESCRIPTION_CAP, clientVisibleLength } from '../../tool-registry/description-length.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { registerSkillsTools } from '../skills.tools.js';
+import type { ISkillService, Skill } from '../skills.contract.js';
+
+/**
+ * The two skill tools name the skills the caller may read in their
+ * descriptions. The catalog is the organisation's to grow, and a client cuts
+ * a long description from the END — so the names are the part that gives way,
+ * never the tool's own text, and never an id cut in half.
+ */
+describe('the skill tools name the available skills within the description cap', () => {
+  const unused = () => new Proxy({}, { get: () => undefined }) as never;
+
+  async function served(skills: readonly Skill[]) {
+    const registry = new ToolRegistry();
+    const skillService = { listSkills: async () => skills } as unknown as ISkillService;
+    registerSkillsTools(registry, express.Router(), ((_req, _res, next) => next()) as unknown as ToolAuth, createToolHandlerFactory(unused()), skillService);
+    const tools = await registry.listExternal();
+    return {
+      list: tools.find((t) => t.name === 'list_skills')!,
+      get: tools.find((t) => t.name === 'get_skill')!,
+    };
+  }
+
+  const skill = (name: string): Skill => ({ name, description: '', path: `Skills/${name}` }) as unknown as Skill;
+
+  it('names every skill when they fit, and says so plainly when there are none', async () => {
+    const few = await served(['rfi', 'deck-review'].map(skill));
+    for (const tool of [few.list, few.get]) {
+      expect(tool.description).toContain('Currently available skills: `rfi`, `deck-review`.');
+      expect(tool.description).not.toContain(' more');
+    }
+    const none = await served([]);
+    expect(none.list.description).toContain('No skills are currently available.');
+  });
+
+  it('lists every skill when the complete line fits, even where a shorter list plus its count would not', async () => {
+    // The budget is what the tool's fixed text leaves under the cap once the
+    // guide-first sentence is counted — read off a served description rather
+    // than guessed, so the names below are sized to fill it EXACTLY.
+    const probe = await served([skill('x')]);
+    const fixed = probe.list.description!.slice(GUIDE_FIRST_SENTENCE.length + 1, probe.list.description!.indexOf('Currently available skills: '));
+    const budget = TOOL_DESCRIPTION_CAP - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
+    const head = 'Currently available skills: '.length;
+    // Twenty-one names, the LAST one short — shorter than the ", and 1 more…"
+    // tail a cut before it would carry — and the first one sized so the
+    // complete line is the budget to the character. A cut-then-count loop
+    // stops short of the complete list here (a prefix plus its count tail is
+    // over budget well before the last name) though the complete line fits.
+    const count = 21;
+    const base = Math.floor((budget - head - 1 - (count - 1) * 2 - count * 2) / count); // chars inside the backticks
+    const names = Array.from({ length: count }, (_, i) => `n${i}`.padEnd(base, 'x'));
+    names[count - 1] = 'z';
+    const slack = budget - (head + names.reduce((n, name) => n + name.length + 2, 0) + (count - 1) * 2 + 1);
+    names[0] = names[0] + 'y'.repeat(slack);
+    const { list } = await served(names.map(skill));
+    const line = list.description!.slice(list.description!.indexOf('Currently available skills: '));
+    expect(line.length).toBe(budget);
+    expect(line.endsWith('.')).toBe(true);
+    expect(line).not.toContain(' more');
+    for (const name of names) expect(line).toContain(`\`${name}\``);
+  });
+
+  it('cuts the list to what fits under the cap with the guide-first sentence counted, and counts the rest', async () => {
+    const many = Array.from({ length: 300 }, (_, i) => skill(`a-skill-with-a-long-name-number-${i}`));
+    const { list, get } = await served(many);
+    for (const tool of [list, get]) {
+      // Measured as the registry serves it: the opener in front.
+      expect(clientVisibleLength(tool), tool.name).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+      expect(tool.description!.startsWith(GUIDE_FIRST_SENTENCE), tool.name).toBe(true);
+      // The tool's own text is whole; the names are what gave way.
+      expect(tool.description, tool.name).toContain('Currently available skills: `a-skill-with-a-long-name-number-0`');
+      const counted = /, and (\d+) more that list_skills names\.$/.exec(tool.description!);
+      expect(counted, tool.name).not.toBeNull();
+      const shown = (tool.description!.match(/`a-skill-with-a-long-name-number-\d+`/g) ?? []).length;
+      expect(shown + Number(counted![1]), tool.name).toBe(300);
+      // No name is cut in half: every one listed is a real one, closing
+      // backtick included — a dangling name (no closing backtick) is caught
+      // because the scan does not require one.
+      for (const name of tool.description!.match(/`a-skill-with-a-long-name-number-[^`,.]*`?/g) ?? []) {
+        expect(name, tool.name).toMatch(/^`a-skill-with-a-long-name-number-\d+`$/);
+      }
+    }
+  });
+});

package/src/modules/skills/skills.tools.ts

@@ -1,5 +1,7 @@
 import type { Router, RequestHandler } from 'express';
 import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
+import { GUIDE_FIRST_SENTENCE } from '../tool-registry/guide-first.js';
 import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
@@ -97,25 +99,66 @@ function branchArg(args: Record<string, unknown>): string | undefined {
   return typeof branch === 'string' && branch.trim().length > 0 ? branch : undefined;
 }
 
-/** "Currently available skills: `a`, `b`." (or a no-skills note), filtered to what the caller may read. */
-async function availableSkillsLine(skillService: ISkillService, userEmail?: string): Promise<string> {
+/**
+ * "Currently available skills: `a`, `b`." (or a no-skills note), filtered to
+ * what the caller may read, and cut to `budget` characters: as many names as
+ * fit, then a count of the rest. The names are a convenience — `list_skills`
+ * is the complete answer — and a description a client cuts from the end
+ * would lose the tool's own tail to a catalog that grew; the budget is what
+ * the tool's fixed text leaves under {@link TOOL_DESCRIPTION_CAP} once the
+ * guide-first sentence the registry puts in front is counted.
+ */
+async function availableSkillsLine(skillService: ISkillService, userEmail: string | undefined, budget: number): Promise<string> {
   const skills = await skillService.listSkills(userEmail);
   if (skills.length === 0) return 'No skills are currently available.';
-  return `Currently available skills: ${skills.map((s) => `\`${s.name}\``).join(', ')}.`;
+  const names = skills.map((s) => `\`${s.name}\``);
+  const rest = (shown: number): string =>
+    shown < names.length ? `, and ${names.length - shown} more that list_skills names.` : '.';
+  const head = 'Currently available skills: ';
+  // The complete line first: it ends in a full stop, not in a count, so it
+  // can fit where a shorter list plus its "and N more" tail would not.
+  const complete = `${head}${names.join(', ')}.`;
+  if (complete.length <= budget) return complete;
+  // Otherwise one pass, accumulating: the cut is where the next name — with
+  // the separator before it and the tail that would follow it — no longer
+  // fits. (Rebuilding the joined prefix per candidate made this quadratic in
+  // the catalog's size, on every catalog listing.)
+  let shown = 0;
+  let length = head.length;
+  for (const name of names) {
+    const added = (shown > 0 ? 2 : 0) + name.length;
+    if (length + added + rest(shown + 1).length > budget) break;
+    length += added;
+    shown += 1;
+  }
+  if (shown === 0) {
+    return names.length === 1
+      ? '1 skill is currently available; list_skills names it.'
+      : `${names.length} skills are currently available; list_skills names them.`;
+  }
+  return `${head}${names.slice(0, shown).join(', ')}${rest(shown)}`;
+}
+
+/** What the fixed part of a description leaves the skills line, with the guide-first sentence counted. */
+function skillsLineBudget(fixed: string): number {
+  return TOOL_DESCRIPTION_CAP - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
 }
 
+const LIST_SKILLS_DESCRIPTION =
+  'List the available skills (reusable specialist instructions) with their names, descriptions and, ' +
+  'for a skill that declares one, its current `version` (its SKILL.md `metadata.version`, else a ' +
+  'top-level `version`, else `lifecycle.version`). ' +
+  'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
+  'Pass `branch` to list the skills as they are on a draft branch instead of the released set — ' +
+  'what you need to try a skill you just wrote there; each skill that differs from the released ' +
+  'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ';
+
 async function buildListSkillsDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
     name: 'list_skills',
     description:
-      'List the available skills (reusable specialist instructions) with their names, descriptions and, ' +
-      'for a skill that declares one, its current `version` (its SKILL.md `metadata.version`, else a ' +
-      'top-level `version`, else `lifecycle.version`). ' +
-      'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
-      'Pass `branch` to list the skills as they are on a draft branch instead of the released set — ' +
-      'what you need to try a skill you just wrote there; each skill that differs from the released ' +
-      'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ' +
-      (await availableSkillsLine(skillService, userEmail)),
+      LIST_SKILLS_DESCRIPTION +
+      (await availableSkillsLine(skillService, userEmail, skillsLineBudget(LIST_SKILLS_DESCRIPTION))),
     path: '/api/agent/tools/list_skills',
     inputs: {
       type: 'object',
@@ -156,15 +199,18 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
   });
 }
 
+const GET_SKILL_DESCRIPTION =
+  'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
+  'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
+  '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
+  'one the skill declared, or `branch` names a draft to load it from. ';
+
 async function buildGetSkillDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
     name: 'get_skill',
     description:
-      'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
-      'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
-      '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
-      'one the skill declared, or `branch` names a draft to load it from. ' +
-      (await availableSkillsLine(skillService, userEmail)),
+      GET_SKILL_DESCRIPTION +
+      (await availableSkillsLine(skillService, userEmail, skillsLineBudget(GET_SKILL_DESCRIPTION))),
     path: '/api/agent/tools/get_skill',
     inputs: {
       type: 'object',

package/src/modules/tool-manuals/__tests__/tool-manuals.detail.route.test.ts

@@ -34,6 +34,7 @@ const DETAIL: ToolManualDetail = {
   type: 'inline',
   description: 'Read and write GitHub issues and PRs.',
   capabilities: [{ name: 'create_issue', description: 'Open an issue in a repo.' }],
+  hiddenTools: [],
 };
 
 let httpServer: HttpServer | undefined;
@@ -205,6 +206,62 @@ describe('ToolManualService.getDetail — capabilities + access', () => {
     });
   });
 
+  /**
+   * The tool page's half of the marker. The finding comes from the MCP proxy,
+   * which is the only thing that loads a connected server's tools; what this
+   * endpoint decides is WHO sees it — the people who may write the `.tool`,
+   * and nobody else.
+   */
+  describe('a tool of this server hidden for an invalid schema', () => {
+    const HIDDEN = {
+      manual: 'remote',
+      name: 'remote_srv_query',
+      path: '/properties/value/anyOf/0/required/0',
+      reason: 'must be a string',
+      marker:
+        'Hidden from agents: its schema is invalid at /properties/value/anyOf/0/required/0 (must be a string).',
+    };
+
+    const writer = (allowed: boolean): IAccessControl =>
+      ({
+        canRead: async () => true,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+        canWrite: async () => allowed,
+      }) as unknown as IAccessControl;
+
+    test('is reported to a caller who may write the tool', async () => {
+      await withTool('remote.tool', JSON.stringify({ name: 'remote', type: 'mcp', url: 'https://mcp.example.com/mcp' }));
+      const service = svc(writer(true));
+      service.setHiddenTools({ hiddenFor: (manual) => (manual === 'remote' ? [HIDDEN] : []) });
+      expect((await service.getDetail('owner@x.eu', 'remote'))?.hiddenTools).toEqual([HIDDEN]);
+    });
+
+    test('is withheld from a caller who may only read it', async () => {
+      await withTool('remote.tool', JSON.stringify({ name: 'remote', type: 'mcp', url: 'https://mcp.example.com/mcp' }));
+      const service = svc(writer(false));
+      service.setHiddenTools({ hiddenFor: () => [HIDDEN] });
+      expect((await service.getDetail('reader@x.eu', 'remote'))?.hiddenTools).toEqual([]);
+    });
+
+    test('is empty, and costs no write check, when the server is healthy', async () => {
+      await withTool('remote.tool', JSON.stringify({ name: 'remote', type: 'mcp', url: 'https://mcp.example.com/mcp' }));
+      const canWrite = vi.fn(async () => true);
+      const service = svc({
+        canRead: async () => true,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+        canWrite,
+      } as unknown as IAccessControl);
+      service.setHiddenTools({ hiddenFor: () => [] });
+      expect((await service.getDetail('owner@x.eu', 'remote'))?.hiddenTools).toEqual([]);
+      expect(canWrite).not.toHaveBeenCalled();
+    });
+
+    test('is empty when no MCP surface has loaded a server yet', async () => {
+      await withTool('remote.tool', JSON.stringify({ name: 'remote', type: 'mcp', url: 'https://mcp.example.com/mcp' }));
+      expect((await svc().getDetail('owner@x.eu', 'remote'))?.hiddenTools).toEqual([]);
+    });
+  });
+
   test('description is null (not undefined) when the file declares none', async () => {
     await withTool('bare.tool', JSON.stringify({ name: 'bare', type: 'inline', tools: [] }));
     const detail = await svc().getDetail('user@x.eu', 'bare');

package/src/modules/tool-manuals/__tests__/tool-manuals.tools.test.ts

@@ -9,6 +9,7 @@ import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { registerToolManualsTools } from '../tool-manuals.tools.js';
 import type { IToolManualService } from '../tool-manuals.contract.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import type { HiddenTool, HiddenToolSource } from '../../../shared/hidden-tools.js';
 
 /**
  * `list_tool_setup` MUST respect the same access controls as every other tool
@@ -31,7 +32,10 @@ const BOB = { id: 'user-bob', email: 'bob@x.com', name: 'Bob' };
 const CATALOG = [
   {
     slug: 'weather',
-    name: 'weather',
+    // The catalog NAME differs from the slug on purpose: the hidden-tool
+    // source is keyed by name, and a lookup keyed by slug would pass a
+    // fixture where the two are the same string.
+    name: 'Weather Service',
     path: 'Plugins/weather.tool',
     type: 'mcp' as const,
     setup: { kind: 'oauth-manual' as const, reason: 'no dynamic client registration' },
@@ -93,7 +97,16 @@ const externalApiKeyService = {
     t === 'bevel_alice' ? { user: ALICE, tokenId: 'tok-a' } : t === 'bevel_bob' ? { user: BOB, tokenId: 'tok-b' } : null,
 } as never;
 
-async function start(): Promise<string> {
+/** What the proxy's schema check found for `weather`, when a test wires one in. */
+const HIDDEN_WEATHER_TOOL: HiddenTool = {
+  manual: 'Weather Service',
+  name: 'weather_srv_forecast',
+  path: '/properties/value/anyOf/0/required/0',
+  reason: 'must be a string',
+  marker: 'Hidden from agents: its schema is invalid at /properties/value/anyOf/0/required/0 (must be a string).',
+};
+
+async function start(hiddenTools?: HiddenToolSource): Promise<string> {
   const registry = new ToolRegistry();
   const internalToken = new InternalTokenService({ secret: 'test-secret' });
   const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
@@ -116,6 +129,7 @@ async function start(): Promise<string> {
     accessControl,
     variableStatus: { statusFor },
     kb: testKbContext(),
+    hiddenTools,
   });
   app.use('/api', router);
 
@@ -158,8 +172,10 @@ describe('list_tool_setup — access controls resolved for the caller', () => {
     // Bob can't read billing — it must be absent, not just canWrite=false.
     expect(bob.tools.map((t) => t.slug)).toEqual(['weather']);
     expect(bob.tools[0].canWrite).toBe(false);
-    // Status was resolved for BOB's user id, not leaked from Alice's.
-    expect(statusFor).toHaveBeenLastCalledWith(BOB.id, ['weather_SHARED_KEY']);
+    // Status was resolved for BOB's user id, not leaked from Alice's — under
+    // the key the vault derives from the manual's NAME (`Weather Service`:
+    // the space becomes `_`, every `_` is doubled, then the variable).
+    expect(statusFor).toHaveBeenLastCalledWith(BOB.id, ['Weather__Service_SHARED_KEY']);
     expect(bob.tools[0].variables[0].userConfigured).toBe(false);
   });
 
@@ -182,6 +198,59 @@ describe('list_tool_setup — access controls resolved for the caller', () => {
     expect(bob.invalid).toEqual([]);
   });
 
+  it('marks a tool hidden for an invalid schema, to the caller who may manage the server', async () => {
+    const base = await start({
+      hiddenFor: (manual) => (manual === 'Weather Service' ? [HIDDEN_WEATHER_TOOL] : []),
+    });
+
+    const alice = (await (await callSetup(base, 'bevel_alice')).json()) as {
+      tools: { slug: string; hiddenTools: HiddenTool[] }[];
+    };
+    // Alice writes `weather`, so she is the one who can get the schema fixed.
+    expect(alice.tools.find((t) => t.slug === 'weather')!.hiddenTools).toEqual([HIDDEN_WEATHER_TOOL]);
+    // The marker names the tool, the place and the reason, in one sentence.
+    expect(alice.tools.find((t) => t.slug === 'weather')!.hiddenTools[0].marker).toBe(
+      'Hidden from agents: its schema is invalid at /properties/value/anyOf/0/required/0 (must be a string).',
+    );
+    // Nothing is wrong with `billing`, which Alice cannot write anyway.
+    expect(alice.tools.find((t) => t.slug === 'billing')!.hiddenTools).toEqual([]);
+
+    // Bob READS `weather` and cannot write it: the marker is not his to see.
+    // He has no way to fix the schema, and the hidden tool is simply not among
+    // the ones he can call.
+    const bob = (await (await callSetup(base, 'bevel_bob')).json()) as {
+      tools: { slug: string; hiddenTools: HiddenTool[] }[];
+    };
+    expect(bob.tools.map((t) => t.slug)).toEqual(['weather']);
+    expect(bob.tools[0].hiddenTools).toEqual([]);
+  });
+
+  it('reports no hidden tool on a deployment with no MCP surface at all — no source wired', async () => {
+    const base = await start(); // no source wired, as a deployment without the proxy
+    const alice = (await (await callSetup(base, 'bevel_alice')).json()) as {
+      tools: { slug: string; hiddenTools: HiddenTool[] }[];
+    };
+    for (const tool of alice.tools) expect(tool.hiddenTools).toEqual([]);
+  });
+
+  it('reports no hidden tool to a manager whose server is healthy, or has not loaded yet — source wired, nothing found', async () => {
+    // The distinct case from the one above: the proxy IS there and has nothing
+    // against `weather`, which Alice manages. `[]` is the finding, not the
+    // absence of a finder.
+    const hiddenFor = vi.fn((): HiddenTool[] => []);
+    const base = await start({ hiddenFor });
+    const alice = (await (await callSetup(base, 'bevel_alice')).json()) as {
+      tools: { slug: string; canWrite: boolean; hiddenTools: HiddenTool[] }[];
+    };
+    const weather = alice.tools.find((t) => t.slug === 'weather')!;
+    expect(weather.canWrite).toBe(true);
+    expect(weather.hiddenTools).toEqual([]);
+    // Asked by the manual's catalog NAME, which is how the proxy knows it —
+    // not by its slug — and the answer came from the source.
+    expect(hiddenFor).toHaveBeenCalledWith('Weather Service');
+    expect(hiddenFor).not.toHaveBeenCalledWith('weather');
+  });
+
   it('rejects an unauthenticated call outright', async () => {
     const base = await start();
     const res = await fetch(`${base}/api/agent/tools/list_tool_setup`, {

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

@@ -1,4 +1,5 @@
 import type { CallTemplate } from '@utcp/sdk';
+import type { HiddenTool, HiddenToolSource } from '../../shared/hidden-tools.js';
 
 /**
  * Tool manuals — user-authored `*.tool` files under `Plugins/` in the DEFAULT
@@ -329,10 +330,11 @@ export interface ToolCapability {
 
 /**
  * A single tool manual for the BROWSER tool page (`GET /api/tools/:slug`): the
- * summary plus the two human-facing fields the catalog listing has no use for.
- * Both are normalized to `null` rather than left optional — the page renders a
- * definite "nothing here" state, so an absent field and an empty one are the
- * same thing to it.
+ * summary plus the three human-facing fields the catalog listing has no use
+ * for — the description, the capabilities and the tools hidden for an invalid
+ * schema. Each is normalized to a definite empty (`null`, `[]`) rather than
+ * left optional — the page renders a definite "nothing here" state, so an
+ * absent field and an empty one are the same thing to it.
  */
 export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'> {
   description: string | null;
@@ -342,6 +344,16 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
    * round-trip this endpoint deliberately does not make), so they report `[]`.
    */
   capabilities: ToolCapability[];
+  /**
+   * Tools of this manual that Hexis keeps off every agent surface because
+   * their input schema is not valid JSON Schema as the server sent it, each
+   * with the place and the reason.
+   *
+   * Only for a caller who may WRITE this manual's file: the marker is for the
+   * people who manage the server, who are the only ones who can get the schema
+   * fixed. `[]` for everyone else, and for a server with nothing wrong.
+   */
+  hiddenTools: HiddenTool[];
 }
 
 export interface IToolManualService {
@@ -374,6 +386,14 @@ export interface IToolManualService {
    */
   getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
 
+  /**
+   * Wire where a hidden tool's schema finding comes from (the MCP proxy, which
+   * is constructed after this service — setter injection for the same reason
+   * `setMcpAuthDiscovery` is one). Without it `getDetail` reports no hidden
+   * tool, which is the honest answer for a deployment with no MCP surface.
+   */
+  setHiddenTools(source: HiddenToolSource): void;
+
   /**
    * 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

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

@@ -32,6 +32,7 @@ import { RESERVED_VARIABLE_NAMES, findReservedVariableRef } from '../../shared/v
 import { extractFrontmatter, resolveDeclaredId, isValidId, dedupeById } from '../../shared/frontmatter-id.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
+import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 import {
   utcpNamespacePrefix,
   utcpNamespacedKey,
@@ -239,6 +240,8 @@ export type McpAuthDiscoveryResult =
 export class ToolManualService implements IToolManualService {
   private readonly cache: TtlCache<ScanResult>;
   private mcpAuthDiscovery?: McpAuthDiscoveryPort;
+  /** Where a hidden tool's schema finding comes from; absent until wired. */
+  private hiddenTools?: HiddenToolSource;
   /**
    * The refused set as it was last written to the log, so the warnings are
    * logged ONCE PER CHANGE rather than once per scan. A broken `.tool` sits
@@ -288,6 +291,10 @@ export class ToolManualService implements IToolManualService {
     this.mcpAuthDiscovery = discovery;
   }
 
+  setHiddenTools(source: HiddenToolSource): void {
+    this.hiddenTools = source;
+  }
+
   invalidate(): void {
     this.cache.invalidate();
     this.inFlightScan = null;
@@ -317,10 +324,20 @@ export class ToolManualService implements IToolManualService {
     // model, no second place for the access rules to drift.
     const found = (await this.accessibleManuals(userEmail)).find((m) => m.slug === slug);
     if (!found) return null;
+    // The marker is for whoever manages the server: the same per-file write
+    // verdict that gates setting the tool's shared secrets. A reader sees
+    // nothing of it — they can neither fix the schema nor do anything with the
+    // knowledge that one of the server's tools is off. The write check is
+    // asked only when there is something to show, so the healthy case (every
+    // tool of every server) costs no ACL round-trip.
+    const hidden = this.hiddenTools?.hiddenFor(found.name) ?? [];
+    const mayManage =
+      hidden.length > 0 && (await this.accessControl.canWrite(this.kb.defaultWorkspaceId(), userEmail, found.path));
     return {
       ...toSummary(found),
       description: found.description ?? null,
       capabilities: capabilitiesOf(found),
+      hiddenTools: mayManage ? hidden : [],
     };
   }