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

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 : [],
     };
   }
 

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

@@ -3,10 +3,12 @@ import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js'
 import type { KbContext } from '../../shared/kb-context.js';
 import type { ToolContext } from '../tool-helpers/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
+import { declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IToolManualService } from './tool-manuals.contract.js';
+import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 
 /**
  * What `list_tool_setup` needs from the secrets vault (structurally satisfied
@@ -43,10 +45,21 @@ export function registerToolManualsTools(
     variableStatus: VariableStatusPort;
     /** Which branch tools are served from, and its clone. */
     kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId'>;
+    /**
+     * Where a hidden tool's schema finding comes from (the MCP proxy).
+     * Optional: a deployment with no MCP surface has nothing to report, and
+     * `hiddenTools` is then empty everywhere.
+     */
+    hiddenTools?: HiddenToolSource;
   },
 ): void {
   registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
   registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+  // The def above is built per catalog listing (its description names the
+  // tools configured for THIS caller), so declare the arguments here as well:
+  // a direct REST call that lands before the first listing must be checked
+  // against them too.
+  declareRouteTool('list_local_tools', LIST_LOCAL_TOOLS_INPUTS);
 
   router.post(
     '/agent/tools/list_local_tools',
@@ -66,23 +79,31 @@ export function registerToolManualsTools(
   const listSetupDef = toolDef({
     name: 'list_tool_setup',
     // What each FIELD means is documented on the field, in `outputs` below:
-    // `setup.kind`, `variables` and `invalid` each carried a paragraph here,
-    // which made this description two thousand characters and so the first
-    // thing a client cut. The description says what the tool answers and the
-    // three things an agent cannot read off a field.
+    // `setup.kind`, `variables`, `invalid` and `hiddenTools` each carried a
+    // paragraph here, which made this description two thousand characters and
+    // so the first thing a client cut. The description says what the tool
+    // answers and the four things an agent cannot read off a field.
+    //
+    // It sits a few characters under `TOOL_DESCRIPTION_CAP` WITH the guide-first
+    // sentence the registry puts in front of it (`tool-registry/guide-first.ts`)
+    // and the `Call:` line generated ahead of everything,
+    // which is why every sentence here is the short form: the `hiddenTools`
+    // clause and that opener both came out of the same budget, and what a
+    // hidden tool's entry CONTAINS is on the field below rather than here.
     description:
-      'Configuration status of every `.tool` the current user can access: what each tool needs set up and what is ' +
-      'already configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER — a `.tool` it cannot ' +
-      'READ is absent entirely, and every flag is the caller\'s own state. ' +
-      'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool editor, ' +
-      'and users sign in on /connect rather than typing a value. ' +
-      'What gates setting a tool\'s shared secrets is `canWrite` on the `.tool` FILE — per-file access from its ' +
-      'frontmatter `write:`/`owner:` verbs and the access.md chain, NOT a platform role: the people who manage the ' +
-      'file configure the tool. ' +
+      'Configuration status of every `.tool` the current user can access: what each needs set up and what is ' +
+      'configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot ' +
+      'READ is absent, and every flag is the caller\'s own. ' +
+      'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool ' +
+      'editor; users sign in on /connect. ' +
+      'Setting a tool\'s shared secrets is gated by `canWrite` on the `.tool` FILE (its frontmatter ' +
+      '`write:`/`owner:` verbs and the access.md chain), NOT by a platform role: who manages the file configures ' +
+      'the tool. ' +
+      '`hiddenTools` names the tools Hexis hides from agents for an invalid schema. ' +
       'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you declared on a ' +
-      'draft is not listed, not callable and not signed-in-able until that draft is merged. Pass `branch` (the draft ' +
-      'you wrote the declaration on) and `onBranchOnly` names every tool declared there that the default branch does ' +
-      'not serve yet — open a change request, then ask the user to review and merge it in the app to activate it.',
+      'draft is not listed, callable or signed-in-able until it is merged. Pass `branch` (the draft you wrote the ' +
+      'declaration on) and `onBranchOnly` names every tool declared there that the default branch does not serve ' +
+      'yet — open a change request and ask the user to merge it.',
     path: '/api/agent/tools/list_tool_setup',
     inputs: {
       type: 'object',
@@ -132,6 +153,22 @@ export function registerToolManualsTools(
                 type: 'boolean',
                 description: 'You may write this `.tool` FILE, which is what gates setting its shared secrets.',
               },
+              hiddenTools: {
+                type: 'array',
+                description:
+                  'Tools of this server kept off every agent surface for an invalid input schema. Empty ' +
+                  'unless the caller may write this tool.',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name: { type: 'string', description: 'The name the tool would have been offered under.' },
+                    path: { type: 'string', description: 'JSON Pointer to the place in the schema that is not valid.' },
+                    reason: { type: 'string', description: 'Why that place is not valid, in the validator\'s words.' },
+                    marker: { type: 'string', description: 'The one sentence the tool page shows for this tool.' },
+                  },
+                  required: ['name', 'path', 'reason', 'marker'],
+                },
+              },
               variables: {
                 type: 'array',
                 description:
@@ -156,7 +193,7 @@ export function registerToolManualsTools(
                 },
               },
             },
-            required: ['slug', 'name', 'path', 'type', 'canWrite', 'variables'],
+            required: ['slug', 'name', 'path', 'type', 'canWrite', 'hiddenTools', 'variables'],
           },
         },
         invalid: {
@@ -219,27 +256,35 @@ export function registerToolManualsTools(
       const status = await deps.variableStatus.statusFor(ctx.user.id, allKeys);
       const statusByKey = new Map(status.map((s) => [s.key, s]));
       const tools = await Promise.all(
-        manuals.map(async (m) => ({
-          slug: m.slug,
-          name: m.name,
-          path: m.path,
-          type: m.type,
-          setup: m.setup ?? null,
-          canWrite: await deps.accessControl.canWrite(defaultWs(), ctx.user.email, m.path),
-          variables: (m.variables ?? []).map((v) => {
-            const st = statusByKey.get(varKey(m.name, v.name));
-            const isOAuth = v.oauth != null;
-            return {
-              name: v.name,
-              scope: v.scope,
-              label: v.label ?? null,
-              oauth: isOAuth,
-              adminConfigured: st?.adminConfigured ?? false,
-              userConfigured: st?.userConfigured ?? false,
-              authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
-            };
-          }),
-        })),
+        manuals.map(async (m) => {
+          const canWrite = await deps.accessControl.canWrite(defaultWs(), ctx.user.email, m.path);
+          return {
+            slug: m.slug,
+            name: m.name,
+            path: m.path,
+            type: m.type,
+            setup: m.setup ?? null,
+            canWrite,
+            // The marker goes only to the people who manage the server — the
+            // same verdict that gates setting its shared secrets. A caller who
+            // may only READ the tool is told nothing about it: they cannot fix
+            // the schema, and the tool is simply not among the ones they can call.
+            hiddenTools: canWrite ? (deps.hiddenTools?.hiddenFor(m.name) ?? []) : [],
+            variables: (m.variables ?? []).map((v) => {
+              const st = statusByKey.get(varKey(m.name, v.name));
+              const isOAuth = v.oauth != null;
+              return {
+                name: v.name,
+                scope: v.scope,
+                label: v.label ?? null,
+                oauth: isOAuth,
+                adminConfigured: st?.adminConfigured ?? false,
+                userConfigured: st?.userConfigured ?? false,
+                authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
+              };
+            }),
+          };
+        }),
       );
       const onBranchOnly = pending.map((p) => ({ ...p, branch: branch! }));
       if (onBranchOnly.length === 0) return { tools, invalid, onBranchOnly };
@@ -265,6 +310,9 @@ async function localToolsLine(svc: IToolManualService, userEmail?: string): Prom
   return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
 }
 
+/** `list_local_tools` takes nothing; a const so the route and the def share one declaration. */
+const LIST_LOCAL_TOOLS_INPUTS = { type: 'object' as const, properties: {}, additionalProperties: false };
+
 async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
     name: 'list_local_tools',
@@ -280,7 +328,7 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
       'setup by hand. ' +
       (await localToolsLine(svc, userEmail)),
     path: '/api/agent/tools/list_local_tools',
-    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    inputs: LIST_LOCAL_TOOLS_INPUTS,
     outputs: {
       type: 'object',
       properties: {

package/src/modules/tool-registry/__tests__/own-tool-schemas.test.ts

@@ -0,0 +1,173 @@
+import { readFileSync } from 'node:fs';
+import express from 'express';
+import { describe, expect, it } from 'vitest';
+import { inputSchemaDefect } from '@bevel-software/platform-mcp-core';
+import { ToolRegistry } from '../tool-registry.js';
+import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
+import { registerChangeRequestReadTools } from '../../workflow/agent-tools/change-request-read.tools.js';
+import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
+import { registerSkillsTools } from '../../skills/skills.tools.js';
+import { registerPluginsTools } from '../../plugins/plugins.tools.js';
+import { registerToolManualsTools } from '../../tool-manuals/tool-manuals.tools.js';
+import { registerEmbedTools } from '../../embed/embed.tools.js';
+import { registerAgentGuideTool } from '../../agent-guide/agent-guide.tools.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+
+/**
+ * Every tool Hexis declares itself, checked against the same JSON Schema rules
+ * a connected server's tool is checked against.
+ *
+ * Hexis hides a connected tool whose input schema is invalid, because an AI
+ * client would otherwise drop it in silence. The platform's own tools go to
+ * those same clients through those same surfaces, so a mistake in one of these
+ * schemas costs the tool just as quietly — and it would be Hexis's mistake.
+ * This test is the thing that makes shipping one impossible.
+ *
+ * It registers the DEFS as `create-core-server` does, with stubs for the
+ * services (no def-building path touches one: the lazy providers are resolved
+ * with no caller context, which is their static form).
+ *
+ * Add a tool module to the server and this test FAILS until it is added here:
+ * `covers every tool module the server registers` reads the server's own source
+ * and compares the `register…Tools` calls in it with `MODULES` below. A test
+ * that silently skipped a whole module's schemas would be worse than no test,
+ * because it would read as if it had checked them.
+ */
+
+/**
+ * A stub service: every method answers with an empty list. The def-building
+ * paths that do reach a service only ask it what exists (which skills, which
+ * local-only tools) to name them in a description, and "none" is a valid
+ * answer that keeps the SCHEMAS — what this test is about — untouched.
+ * `then` is excluded so the stub is never mistaken for a promise.
+ */
+const nothing = new Proxy(
+  {},
+  {
+    get: (_target, key) => (key === 'then' ? undefined : async () => []),
+  },
+) as never;
+
+const pass: express.RequestHandler = (_req, _res, next) => next();
+const handler = (() => pass) as never;
+
+/** Where the server registers its tool modules — read, not imported, see below. */
+const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import.meta.url);
+
+/** Every tool-registering module, by the name the server calls it under. */
+const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
+  {
+    name: 'registerWorkflowTools',
+    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true),
+  },
+  {
+    name: 'registerChangeRequestReadTools',
+    register: (registry) =>
+      registerChangeRequestReadTools(registry, express.Router(), pass, handler, nothing, testKbContext()),
+  },
+  {
+    name: 'registerWorkspaceTools',
+    register: (registry) =>
+      registerWorkspaceTools(
+        registry,
+        express.Router(),
+        pass,
+        handler,
+        nothing,
+        nothing,
+        nothing,
+        testKbContext(),
+        { recoveryBotEmail: 'recovery@bevel.software', hooks: nothing, notes: new ToolDescriptionNotes() },
+        nothing,
+        nothing,
+        undefined,
+        undefined,
+        // The upload store: the two upload tools are mounted only when one is
+        // supplied, and the server supplies one — so this harness does too,
+        // or their schemas would be the two it silently never checked.
+        nothing,
+      ),
+  },
+  {
+    name: 'registerSkillsTools',
+    register: (registry) => registerSkillsTools(registry, express.Router(), pass, handler, nothing),
+  },
+  { name: 'registerPluginsTools', register: (registry) => registerPluginsTools(registry, testKbContext()) },
+  {
+    name: 'registerEmbedTools',
+    register: (registry) =>
+      registerEmbedTools(registry, express.Router(), pass, handler, {
+        embedService: nothing,
+        kb: testKbContext(),
+        readForTool: nothing,
+        canBeReached: () => true,
+        appUrlFor: (repoRelative) => `https://example.test/workspace/main/knowledge-base/${repoRelative}`,
+        notes: new ToolDescriptionNotes(),
+      }),
+  },
+  {
+    name: 'registerToolManualsTools',
+    register: (registry) =>
+      registerToolManualsTools(registry, express.Router(), pass, handler, nothing, {
+        accessControl: nothing,
+        variableStatus: nothing,
+        kb: testKbContext(),
+      }),
+  },
+  {
+    // The one module registering a single tool: a provider on both surfaces,
+    // built from the sections the reader answers — none here, which still
+    // builds the def.
+    name: 'registerAgentGuideTool',
+    register: (registry) => registerAgentGuideTool(registry, express.Router(), pass, handler, async () => []),
+  },
+];
+
+async function toolsOf(modules: ReadonlyArray<(typeof MODULES)[number]>) {
+  const registry = new ToolRegistry();
+  for (const module of modules) module.register(registry);
+  // Both surfaces: the external one is what reaches a connected AI client, the
+  // internal one is what the in-app agent calls. Either can carry a bad schema.
+  return [...(await registry.listExternal()), ...(await registry.listInternal())];
+}
+
+const allOwnTools = () => toolsOf(MODULES);
+
+describe("Hexis's own tool schemas", () => {
+  /**
+   * The harness's own guard, and the reason it reads a source file: nothing in
+   * the registry can tell this test about a module nobody registered. A count
+   * cannot either — a new module leaves it larger either way. The server's call
+   * list can, and it is the only place that knows the whole set.
+   */
+  it('covers every tool module the server registers', () => {
+    const source = readFileSync(CORE_SERVER_SOURCE, 'utf8');
+    // `register…Tools` and `register…Tool` alike: a module registering one
+    // tool is a module whose schema this harness must check too.
+    const registered = [...source.matchAll(/\b(register\w+Tools?)\s*\(/g)].map((m) => m[1]);
+    expect([...new Set(registered)].sort()).toEqual(MODULES.map((m) => m.name).sort());
+  });
+
+  it.each(MODULES.map((m) => [m.name, m] as const))('%s contributes tools to check', async (_name, module) => {
+    // A module that registers nothing — a renamed registry method, a provider
+    // that threw away its defs — would otherwise pass every assertion below
+    // while exercising nothing.
+    expect(await toolsOf([module])).not.toEqual([]);
+  });
+
+  it('declares valid JSON Schema for every tool, on both surfaces', async () => {
+    const defects = (await allOwnTools())
+      .map((tool) => ({ tool: tool.name, defect: inputSchemaDefect(tool.inputs) }))
+      .filter((entry) => entry.defect !== null);
+    // Named, not counted: a failure has to say WHICH tool and WHERE.
+    expect(defects).toEqual([]);
+  });
+
+  it('declares an object schema for every tool, as MCP requires of an input schema', async () => {
+    const notObjects = (await allOwnTools())
+      .filter((tool) => (tool.inputs as { type?: unknown }).type !== 'object')
+      .map((tool) => tool.name);
+    expect(notObjects).toEqual([]);
+  });
+});