@bevel-software/platform-core-backend 0.31.0 → 0.33.0

package/src/modules/tool-registry/__tests__/read-only-hints.test.ts

@@ -0,0 +1,439 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { flattenManualTool, toListedTool, withReadOnlyOverride } from '@bevel-software/platform-mcp-core';
+import {
+  TOOL_READ_ONLY_SETTING,
+  ToolReadOnlyHints,
+  ToolRegistry,
+  UnknownToolError,
+  createManualRoutes,
+  createToolHintsAgentRoutes,
+  createToolHintsRoutes,
+} from '../index.js';
+import { toolDef } from '../../tool-helpers/index.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/index.js';
+import { registerPluginsTools } from '../../plugins/index.js';
+import { registerToolManualsTools } from '../../tool-manuals/index.js';
+import { registerEmbedTools } from '../../embed/embed.tools.js';
+import { registerAgentGuideTool } from '../../agent-guide/index.js';
+import { ToolDescriptionNotes } from '../../workspace/index.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+
+/**
+ * The read-only hint of every platform tool, as the deployment serves it to
+ * both MCP servers: the `read-only` tag on the agent manual (the hosted
+ * endpoint) and `GET /agent/tool-hints` (`hexis-mcp`). Built from the real
+ * registrars, as `create-core-server` registers them, so a tool that declares
+ * itself wrongly fails here by name.
+ */
+
+/** A stub service: every method answers an empty list (see `own-tool-schemas.test.ts`). */
+const nothing = new Proxy({}, { get: (_t, key) => (key === 'then' ? undefined : async () => []) }) as never;
+const pass: express.RequestHandler = (_req, _res, next) => next();
+const handler = (() => pass) as never;
+
+/** The tools the ticket names as readers, every one of which must list `readOnlyHint: true`. */
+const READERS = [
+  'start_session',
+  'grep',
+  'list_files',
+  'read_file',
+  'file_stat',
+  'request_file_download',
+  'list_branches',
+  'list_skills',
+  'get_skill',
+  'list_local_tools',
+  'list_tool_setup',
+  'get_change_request',
+  'list_change_requests',
+  'list_change_request_files',
+  'list_change_request_reviews',
+  'get_agent_guide',
+];
+
+/*
+ * `ask` is the one reader the ticket names that core does not register: it
+ * comes from a deployment's agent overlay (`ext.tools`), which is not in this
+ * repository, so NOTHING here covers it — its hint is checked on a deployment
+ * that has the overlay. What is pinned here is only the rule an overlay tool
+ * rides on, through tools that are plainly not `ask`.
+ */
+
+/** The tools the ticket names as writers, every one of which must list `readOnlyHint: false`. */
+const WRITERS = [
+  'write_file',
+  'write_files',
+  'edit_file',
+  'save_file',
+  'mkdir',
+  'copy_file',
+  'move_file',
+  'delete_file',
+  'delete_folder',
+  'unzip',
+  'request_file_upload',
+  'apply_file_upload',
+  'create_branch',
+  'switch_branch',
+  'delete_branch',
+  'merge_branch',
+  'commit_change',
+  'share_current_branch',
+  'open_change_request',
+  'update_change_request',
+  'create_plugin',
+  'my_plugin',
+];
+
+/** Writers the in-app agent alone is served: on neither MCP server's listing. */
+const INTERNAL_ONLY = new Set(['switch_branch']);
+
+/** Every tool module the server registers, with stand-in services. */
+function platformRegistry(): ToolRegistry {
+  const registry = new ToolRegistry();
+  const kb = testKbContext();
+  registerWorkflowTools(registry, express.Router(), pass, handler, kb, async () => true);
+  registerChangeRequestReadTools(registry, express.Router(), pass, handler, nothing, kb);
+  registerWorkspaceTools(
+    registry,
+    express.Router(),
+    pass,
+    handler,
+    nothing,
+    nothing,
+    nothing,
+    kb,
+    { recoveryBotEmail: 'recovery@bevel.software', hooks: nothing, notes: new ToolDescriptionNotes() },
+    nothing,
+    nothing,
+    undefined,
+    undefined,
+    nothing,
+    undefined,
+    nothing,
+    undefined,
+    undefined,
+    // The pattern matcher: without one `grep` is not mounted. Its defs are all
+    // this reads, so the stand-in is never asked to search.
+    nothing,
+  );
+  registerSkillsTools(registry, express.Router(), pass, handler, nothing);
+  registerPluginsTools(registry, kb);
+  registerEmbedTools(registry, express.Router(), pass, handler, {
+    embedService: nothing,
+    kb,
+    readForTool: nothing,
+    canBeReached: () => true,
+    appUrlFor: (repoRelative) => `https://example.test/${repoRelative}`,
+    notes: new ToolDescriptionNotes(),
+  });
+  registerToolManualsTools(registry, express.Router(), pass, handler, nothing, {
+    accessControl: nothing,
+    variableStatus: nothing,
+    kb,
+  });
+  registerAgentGuideTool(registry, express.Router(), pass, handler, async () => []);
+  return registry;
+}
+
+/** An admin's user id: what `deployment_settings.updated_by` (a uuid column) records. */
+const ADMIN_ID = '00000000-0000-4000-8000-00000000000a';
+
+/**
+ * Refuse what Postgres refuses: `updated_by` is a uuid referencing `users.id`.
+ * An email there answered every real save with a 500 that a fake taking any
+ * string hid.
+ */
+function assertUuid(by: string | null): void {
+  if (by !== null && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(by)) {
+    throw new Error(`invalid input syntax for type uuid: "${by}"`);
+  }
+}
+
+/** The deployment-settings surface the hints use, over one in-memory row. */
+function memorySettings(initial = '') {
+  const state = { value: initial, writes: 0, updatedBy: null as string | null };
+  return {
+    state,
+    port: {
+      reload: async (key: string) => (key === TOOL_READ_ONLY_SETTING ? state.value : ''),
+      recordIfAbsent: async (_key: string, value: string, by: string | null) => {
+        assertUuid(by);
+        if (state.value) return false;
+        state.value = value;
+        state.writes += 1;
+        state.updatedBy = by;
+        return true;
+      },
+      swapIfValue: async (_key: string, expected: string, next: string | null, by: string | null) => {
+        assertUuid(by);
+        if (state.value !== expected) return false;
+        state.value = next ?? '';
+        state.writes += 1;
+        state.updatedBy = by;
+        return true;
+      },
+    },
+  };
+}
+
+/**
+ * The agent manual as the hosted MCP server lists it: flattened, the overrides
+ * read for this listing joined on, then turned into listing entries.
+ */
+async function hostedListing(registry: ToolRegistry, hints: ToolReadOnlyHints) {
+  const manual = hints.apply(await registry.listExternal());
+  const overrides = await hints.overrides();
+  return new Map(
+    manual
+      .map((t) => flattenManualTool({ ...t, name: `KNOWLEDGE_BASE.${t.name}` }, 'KNOWLEDGE_BASE'))
+      .map((t) => toListedTool(withReadOnlyOverride(t, overrides)))
+      .filter((e): e is NonNullable<typeof e> => e !== null)
+      .map((e) => [e.name, e]),
+  );
+}
+
+describe('the built-in hint of every platform tool', () => {
+  it('lists every reader the ticket names as read-only and every writer as not, from the write declaration', async () => {
+    const registry = platformRegistry();
+    const listing = await hostedListing(registry, new ToolReadOnlyHints(registry, memorySettings().port));
+    for (const name of READERS) expect(listing.get(name)?.annotations, name).toEqual({ readOnlyHint: true });
+    for (const name of WRITERS.filter((n) => !INTERNAL_ONLY.has(n))) {
+      expect(listing.get(name)?.annotations, name).toEqual({ readOnlyHint: false });
+    }
+  });
+
+  it('core registers no `ask`: its hint is the overlay\'s, and is not covered by this file', async () => {
+    expect((await platformRegistry().listExternal()).some((t) => t.name === 'ask')).toBe(false);
+  });
+
+  it('lists an overlay tool that declares no write as a reader, and one declaring `write: true` as a writer', async () => {
+    const registry = platformRegistry();
+    registry.registerExternalTool(
+      toolDef({ name: 'overlay_read', description: 'Reads.', path: '/api/agent/tools/overlay_read', inputs: { type: 'object', properties: {} } }),
+    );
+    // Declared with `write: true` and no `write` tag: the boolean alone must
+    // keep it off the readers.
+    registry.registerExternalTool(
+      toolDef({ name: 'overlay_write', description: 'Writes.', path: '/api/agent/tools/overlay_write', inputs: { type: 'object', properties: {} }, write: true }),
+    );
+    const listing = await hostedListing(registry, new ToolReadOnlyHints(registry, memorySettings().port));
+    expect(listing.get('overlay_read')?.annotations).toEqual({ readOnlyHint: true });
+    expect(listing.get('overlay_write')?.annotations).toEqual({ readOnlyHint: false });
+  });
+
+  it('would list `switch_branch` as a writer: it declares one, and is served to no MCP client at all', async () => {
+    // Internal-only (it steers the in-app agent's next turn), so neither MCP
+    // server lists it. Its declaration still decides its hint, should that change.
+    const registry = platformRegistry();
+    const hints = new ToolReadOnlyHints(registry, memorySettings().port);
+    expect((await registry.listExternal()).some((t) => t.name === 'switch_branch')).toBe(false);
+    const internal = (await registry.listInternal()).find((t) => t.name === 'switch_branch');
+    expect(internal?.tags).toContain('write');
+    const [applied] = hints.apply([internal!]);
+    expect(applied!.tags).not.toContain('read-only');
+  });
+
+  it('carries the hint on EVERY platform tool, and no other annotation', async () => {
+    const registry = platformRegistry();
+    const listing = await hostedListing(registry, new ToolReadOnlyHints(registry, memorySettings().port));
+    expect(listing.size).toBeGreaterThan(READERS.length + WRITERS.length - 1);
+    for (const [name, entry] of listing) {
+      expect(Object.keys(entry.annotations ?? {}), name).toEqual(['readOnlyHint']);
+    }
+  });
+
+  it('agrees with the map `hexis-mcp` reads, meta-tools included', async () => {
+    const registry = platformRegistry();
+    const hints = new ToolReadOnlyHints(registry, memorySettings().port);
+    const listing = await hostedListing(registry, hints);
+    const served = await hints.hints();
+    for (const [name, entry] of listing) expect(served[name], name).toBe(entry.annotations?.readOnlyHint);
+    expect(served).toMatchObject({ list_tools: true, tools_info: true, call_tool_chain: false });
+  });
+
+  it("leaves every tool's name, description and schemas as the registry has them", async () => {
+    const registry = platformRegistry();
+    const before = await registry.listExternal();
+    const after = new ToolReadOnlyHints(registry, memorySettings().port).apply(before);
+    const untagged = (tools: typeof before) => tools.map((t) => ({ ...t, tags: undefined }));
+    expect(untagged(after)).toEqual(untagged(before));
+    // And the registry's own defs are never written to.
+    expect((await registry.listExternal()).some((t) => (t.tags ?? []).includes('read-only'))).toBe(false);
+  });
+});
+
+describe('an override', () => {
+  it('flips a reader and a writer, and a reset puts each back and removes the override', async () => {
+    const registry = platformRegistry();
+    const settings = memorySettings();
+    const hints = new ToolReadOnlyHints(registry, settings.port);
+
+    expect(await hints.set('read_file', false, ADMIN_ID)).toMatchObject({ builtIn: true, override: false, readOnly: false });
+    expect(await hints.set('write_file', true, ADMIN_ID)).toMatchObject({ builtIn: false, override: true, readOnly: true });
+    expect(JSON.parse(settings.state.value)).toEqual({ read_file: false, write_file: true });
+    expect(settings.state.updatedBy).toBe(ADMIN_ID);
+    let listing = await hostedListing(registry, hints);
+    expect(listing.get('read_file')?.annotations).toEqual({ readOnlyHint: false });
+    expect(listing.get('write_file')?.annotations).toEqual({ readOnlyHint: true });
+
+    expect(await hints.set('write_file', null, ADMIN_ID)).toMatchObject({ override: null, readOnly: false });
+    expect(await hints.set('read_file', null, ADMIN_ID)).toMatchObject({ override: null, readOnly: true });
+    // The last override gone is the row gone: every tool on its built-in value.
+    expect(settings.state.value).toBe('');
+    listing = await hostedListing(registry, hints);
+    expect(listing.get('read_file')?.annotations).toEqual({ readOnlyHint: true });
+    expect(listing.get('write_file')?.annotations).toEqual({ readOnlyHint: false });
+  });
+
+  it('applies to a code-mode meta-tool', async () => {
+    const registry = platformRegistry();
+    const hints = new ToolReadOnlyHints(registry, memorySettings().port);
+    expect(await hints.set('call_tool_chain', true, null)).toMatchObject({ kind: 'meta', builtIn: false, readOnly: true });
+    expect(await hints.overrides()).toEqual({ call_tool_chain: true });
+    expect((await hints.hints()).call_tool_chain).toBe(true);
+  });
+
+  it('refuses a name that is neither a platform tool nor a meta-tool', async () => {
+    const registry = platformRegistry();
+    const settings = memorySettings();
+    const hints = new ToolReadOnlyHints(registry, settings.port);
+    await expect(hints.set('serper_search', true, null)).rejects.toBeInstanceOf(UnknownToolError);
+    expect(settings.state.writes).toBe(0);
+  });
+
+  it('stores and reads back a valid name that is also an Object.prototype key', async () => {
+    const settings = memorySettings();
+    const hints = new ToolReadOnlyHints({ listExternal: async () => [
+      toolDef({ name: '__proto__', description: 'An odd name.', path: '/api/agent/tools/__proto__', inputs: { type: 'object', properties: {} } }),
+    ] }, settings.port);
+    expect(await hints.set('__proto__', false, ADMIN_ID)).toMatchObject({ override: false, readOnly: false });
+    expect(settings.state.value).toBe('{"__proto__":false}');
+    expect(Object.hasOwn(await hints.overrides(), '__proto__')).toBe(true);
+    expect((await hints.hints())['__proto__']).toBe(false);
+  });
+
+  it('reads as none when the setting cannot be read, so every listing keeps the built-in hints', async () => {
+    const registry = platformRegistry();
+    const { port } = memorySettings('{"read_file":false}');
+    const hints = new ToolReadOnlyHints(registry, {
+      ...port,
+      reload: async () => {
+        throw new Error('connection terminated');
+      },
+    });
+    expect(await hints.overrides()).toEqual({});
+    expect((await hints.hints()).read_file).toBe(true);
+    const listing = await hostedListing(registry, hints);
+    expect(listing.get('read_file')?.annotations).toEqual({ readOnlyHint: true });
+    expect(listing.get('write_file')?.annotations).toEqual({ readOnlyHint: false });
+  });
+
+  it('reads an unreadable stored value as no override at all', async () => {
+    const registry = platformRegistry();
+    const hints = new ToolReadOnlyHints(registry, memorySettings('{"read_file":"yes"}').port);
+    expect(await hints.overrides()).toEqual({});
+  });
+});
+
+describe('the routes', () => {
+  let server: HttpServer | undefined;
+  afterEach(async () => {
+    await new Promise<void>((r) => (server ? server.close(() => r()) : r()));
+    server = undefined;
+  });
+
+  /** A deployment with the three routes and the agent manual; `x-email` stands in for the session, with its user id. */
+  async function start(admins: string[]) {
+    const registry = platformRegistry();
+    const settings = memorySettings();
+    const hints = new ToolReadOnlyHints(registry, settings.port);
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createManualRoutes(registry, pass, undefined, hints));
+    app.use('/api', createToolHintsAgentRoutes(hints, pass));
+    app.use(
+      '/api',
+      (req, _res, next) => {
+        req.userEmail = req.header('x-email') ?? undefined;
+        req.userId = req.userEmail === 'admin@x' ? ADMIN_ID : req.userEmail ? '00000000-0000-4000-8000-00000000000b' : undefined;
+        next();
+      },
+      createToolHintsRoutes(hints, { isAdmin: async (email) => !!email && admins.includes(email) }),
+    );
+    server = await new Promise<HttpServer>((r) => {
+      const s = app.listen(0, '127.0.0.1', () => r(s));
+    });
+    const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}/api`;
+    const put = (name: string, body: unknown, email: string) =>
+      fetch(`${base}/tool-hints/${name}`, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json', 'x-email': email },
+        body: JSON.stringify(body),
+      });
+    const manualTags = async (name: string) => {
+      const manual = (await (await fetch(`${base}/agent/utcp`)).json()) as { tools: Array<{ name: string; tags: string[] }> };
+      return manual.tools.find((t) => t.name === name)?.tags ?? [];
+    };
+    return { base, settings, put, manualTags };
+  }
+
+  it("refuses a non-admin's write, and writes nothing", async () => {
+    const { put, settings, base } = await start(['admin@x']);
+    const res = await put('write_file', { readOnly: true }, 'member@x');
+    expect(res.status).toBe(403);
+    expect(settings.state.writes).toBe(0);
+    // A non-admin still reads every value, and is told they may not edit.
+    const listed = (await (await fetch(`${base}/tool-hints`, { headers: { 'x-email': 'member@x' } })).json()) as {
+      canEdit: boolean;
+      tools: Array<{ name: string; readOnly: boolean; kind: string }>;
+    };
+    expect(listed.canEdit).toBe(false);
+    // The effective value only: whether an admin overrode it, and what it was, is not theirs to read.
+    expect(listed.tools.find((t) => t.name === 'read_file')).toEqual({ name: 'read_file', readOnly: true, kind: 'platform' });
+    expect(listed.tools.filter((t) => t.kind === 'meta').map((t) => t.name)).toEqual([
+      'list_tools',
+      'tools_info',
+      'call_tool_chain',
+    ]);
+  });
+
+  it("applies an admin's override to the next manual and hint map, and a reset removes it", async () => {
+    const { put, manualTags, base, settings } = await start(['admin@x']);
+    expect(await manualTags('write_file')).not.toContain('read-only');
+
+    const res = await put('write_file', { readOnly: true }, 'admin@x');
+    expect(res.status).toBe(200);
+    // Recorded under the admin's user id — the uuid the column holds — not their email.
+    expect(settings.state.updatedBy).toBe(ADMIN_ID);
+    expect(await res.json()).toMatchObject({ name: 'write_file', override: true, readOnly: true });
+    // The manual keeps the BUILT-IN tag: a listing joins the override on itself.
+    expect(await manualTags('write_file')).not.toContain('read-only');
+    const hints = (await (await fetch(`${base}/agent/tool-hints`)).json()) as { tools: Record<string, boolean> };
+    expect(hints.tools.write_file).toBe(true);
+
+    expect((await put('write_file', { readOnly: null }, 'admin@x')).status).toBe(200);
+    expect(await manualTags('write_file')).not.toContain('read-only');
+    const admin = (await (await fetch(`${base}/tool-hints`, { headers: { 'x-email': 'admin@x' } })).json()) as {
+      canEdit: boolean;
+      tools: Array<{ name: string; override: boolean | null }>;
+    };
+    expect(admin.canEdit).toBe(true);
+    expect(admin.tools.find((t) => t.name === 'write_file')?.override).toBeNull();
+  });
+
+  it('answers 404 for an unknown tool and 400 for a value that is not true, false or null', async () => {
+    const { put, settings } = await start(['admin@x']);
+    expect((await put('serper_search', { readOnly: true }, 'admin@x')).status).toBe(404);
+    expect((await put('read_file', { readOnly: 'yes' }, 'admin@x')).status).toBe(400);
+    expect((await put('read_file', {}, 'admin@x')).status).toBe(400);
+    expect(settings.state.writes).toBe(0);
+  });
+});
+

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

@@ -1,6 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { ToolRegistry } from '../tool-registry.js';
-import type { UtcpTool } from '../tool.contract.js';
+import { declaresWrite, ToolRegistry, type UtcpTool } from '../index.js';
 
 function fakeTool(name: string): UtcpTool {
   return {
@@ -62,3 +61,11 @@ describe('ToolRegistry', () => {
     expect(() => r.registerInternalTool(fakeTool('ask'))).not.toThrow();
   });
 });
+
+describe('declaresWrite', () => {
+  it('is the `write` tag, and nothing else', () => {
+    expect(declaresWrite({ tags: ['write'] })).toBe(true);
+    expect(declaresWrite({ tags: ['read-only', 'files'] })).toBe(false);
+    expect(declaresWrite({ tags: [] })).toBe(false);
+  });
+});

package/src/modules/tool-registry/description-length.ts

@@ -13,8 +13,8 @@
 
 import { callLine, splitCallLine } from '@bevel-software/platform-mcp-core';
 import { TOOL_PREFIX_CAP } from '@bevel-software/platform-shared';
-import { PREFIXED_TOOLS } from '../agent-instructions/compose.js';
-import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
+import { PREFIXED_TOOLS } from '../agent-instructions/index.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
 import { GUIDE_FIRST_SENTENCE } from './guide-first.js';
 import type { UtcpTool } from './tool.contract.js';
 

package/src/modules/tool-registry/index.ts

@@ -0,0 +1,22 @@
+export {
+  declaresWrite,
+  type IToolRegistry,
+  type JsonSchema,
+  type ToolListProvider,
+  type ToolManualContext,
+  type ToolProvider,
+  type UtcpTool,
+} from './tool.contract.js';
+export { ToolRegistry } from './tool-registry.js';
+export { createManualRoutes, type ResolveUserEmail } from './manual.routes.js';
+export type { IToolReadOnlyHints, ToolReadOnlyEntry } from './read-only-hints.contract.js';
+export {
+  TOOL_READ_ONLY_SETTING,
+  ToolReadOnlyHints,
+  UnknownToolError,
+  createToolHintsAgentRoutes,
+  createToolHintsRoutes,
+} from './read-only-hints.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { TOOL_DESCRIPTION_CAP } from './description-length.js';
+export { GET_AGENT_GUIDE_TOOL, GUIDE_FIRST_SENTENCE, guideFirstDescription, withGuideFirst } from './guide-first.js';

package/src/modules/tool-registry/manual.routes.ts

@@ -1,7 +1,8 @@
 import express, { type Request, type RequestHandler } from 'express';
 import { UtcpManualSerializer } from '@utcp/sdk';
-import type { IToolRegistry, ToolManualContext, UtcpTool } from './tool.contract.js';
-import { requireInternalSource } from '../tool-auth/tool-auth.middleware.js';
+import { declaresWrite, type IToolRegistry, type ToolManualContext, type UtcpTool } from './tool.contract.js';
+import { requireInternalSource } from '../tool-auth/index.js';
+import type { IToolReadOnlyHints } from './read-only-hints.contract.js';
 
 /** Resolve a connection-key/internal-token user id to its email (for per-caller provider defs). */
 export type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
@@ -49,14 +50,18 @@ function toManual(tools: UtcpTool[]) {
  * on top of it. (External callers are always write-scoped, so the external
  * manual needs no variant.)
  */
-function isWriteTool(tool: { tags?: string[] }): boolean {
-  return (tool.tags ?? []).includes('write');
-}
-
 export function createManualRoutes(
   registry: IToolRegistry,
   manualAuth: RequestHandler,
   resolveUserEmail?: ResolveUserEmail,
+  /**
+   * The read-only hints (`read-only-hints.ts`), put on the AGENT manual's tools
+   * as the `read-only` tag the hosted MCP endpoint turns into
+   * `annotations.readOnlyHint` — the built-in value; the endpoint joins an
+   * admin's override on at listing time.
+   * Absent, the manual carries the tools' own tags only.
+   */
+  readOnlyHints?: Pick<IToolReadOnlyHints, 'apply'>,
 ): express.Router {
   const router = express.Router();
 
@@ -75,11 +80,12 @@ export function createManualRoutes(
   }
 
   router.get('/agent/utcp', manualAuth, async (req, res) => {
-    res.json(toManual(await registry.listExternal(await context(req))));
+    const tools = await registry.listExternal(await context(req));
+    res.json(toManual(readOnlyHints ? readOnlyHints.apply(tools) : tools));
   });
   router.get('/agent/internal/utcp', manualAuth, requireInternalSource, async (req, res) => {
     const internal = await registry.listInternal(await context(req));
-    const tools = req.toolAuth?.scope === 'read' ? internal.filter((t) => !isWriteTool(t)) : internal;
+    const tools = req.toolAuth?.scope === 'read' ? internal.filter((t) => !declaresWrite(t)) : internal;
     res.json(toManual(tools));
   });
 

package/src/modules/tool-registry/read-only-hints.contract.ts

@@ -0,0 +1,54 @@
+import type { UtcpTool } from './tool.contract.js';
+
+/** One tool's read-only hint as the Tools page shows it. */
+export interface ToolReadOnlyEntry {
+  name: string;
+  /** `platform`: an endpoint of this deployment. `meta`: a feature of the MCP servers. */
+  kind: 'platform' | 'meta';
+  /** What the tool's own declaration makes it. */
+  builtIn: boolean;
+  /** The admin's override, or null when there is none. */
+  override: boolean | null;
+  /** What clients are told: the override when set, else the built-in value. */
+  readOnly: boolean;
+}
+
+/**
+ * What MCP clients are told about each platform tool's and code-mode
+ * meta-tool's effect, and an admin's per-deployment overrides of it. The
+ * routes, the agent manual and the core services depend on this, not on the
+ * implementation (`ToolReadOnlyHints` in `read-only-hints.ts`).
+ */
+export interface IToolReadOnlyHints {
+  /** The overrides in effect, as the database has them now. */
+  overrides(): Promise<Record<string, boolean>>;
+  /**
+   * The given manual tools, each tagged `read-only` exactly when its BUILT-IN
+   * hint is true. Overrides are not in it: a listing joins them on itself.
+   */
+  apply(tools: UtcpTool[]): UtcpTool[];
+  /** Every platform tool, then every meta-tool, with its built-in, override and effective value. */
+  describe(): Promise<ToolReadOnlyEntry[]>;
+  /** Every tool's effective hint, by name. */
+  hints(): Promise<Record<string, boolean>>;
+  /**
+   * Set one tool's override, or remove it (`null`). `updatedBy` is the admin's
+   * user id. Throws `UnknownToolError` for a name that is neither kind of tool.
+   */
+  set(name: string, readOnly: boolean | null, updatedBy: string | null): Promise<ToolReadOnlyEntry>;
+}
+
+/**
+ * Where the overrides are stored: the three operations on one deployment
+ * setting that `ToolReadOnlyHints` needs, and nothing of the settings module's
+ * own shape. `DeploymentSettingsService` is the store the composition root
+ * passes; a test passes anything with these three.
+ */
+export interface ToolReadOnlySettingsStore {
+  /** The setting's value as the database has it now, blank when nothing is set. */
+  reload(key: string): Promise<string>;
+  /** Store `value` only if nothing is stored yet; false when something was. */
+  recordIfAbsent(key: string, value: string, updatedBy: string | null): Promise<boolean>;
+  /** Replace `expected` with `next` (null removes the row); false when the stored value was not `expected`. */
+  swapIfValue(key: string, expected: string, next: string | null, updatedBy: string | null): Promise<boolean>;
+}