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

package/src/modules/mcp/tool-schema-guard.ts

@@ -0,0 +1,196 @@
+/**
+ * The schema check for connected tools, and the memory of what it found.
+ *
+ * An AI client that is handed a tool whose input schema is not valid JSON
+ * Schema drops that tool and says nothing: it is simply missing for the agent,
+ * with nothing in Hexis to look at. So Hexis runs the same check itself, when a
+ * server's tools are LOADED, and:
+ *
+ *  - keeps such a tool off every agent surface, so the agent's picture of what
+ *    it can do matches what it can actually call;
+ *  - remembers the finding for the people who manage that server, who are the
+ *    only ones who can get it fixed (the tool page, `list_tool_setup`).
+ *
+ * WHEN it runs is the point. The verdict is remembered per DISTINCT SCHEMA, so
+ * a server whose tools are unchanged costs one hash and one map lookup per
+ * tool: the JSON Schema check happens when a server's tools are first loaded
+ * and when a refresh brings a schema this process has not seen, and never on a
+ * tool call — which re-derives the surface from those same unchanged schemas.
+ *
+ * It never REPAIRS anything. The proxy passes a connected server's schema
+ * through as sent; an invalid one is reported, and the server's owner decides.
+ */
+
+import { createHash } from 'node:crypto';
+import { inputSchemaDefect, schemaDefectMarker, type SchemaDefect } from '@bevel-software/platform-mcp-core';
+import type { HiddenTool, HiddenToolSource } from '../../shared/hidden-tools.js';
+
+/** What {@link ToolSchemaGuard.screen} needs of a freshly loaded tool. */
+export interface ScreenedTool {
+  /** The UTCP name (`<manual>.<server>.<tool>`) — how the tool repository knows it. */
+  utcpName: string;
+  /** The flattened name an agent addresses it by. */
+  mcpName: string;
+  /** The input schema exactly as the connected server sent it. */
+  inputSchema: unknown;
+}
+
+/**
+ * A finding as the LOADING side needs it. The owner-facing `HiddenTool` is
+ * about a tool by the name an agent would have called it; the proxy also has to
+ * take the tool out of its repository and record it in the audit trail, and
+ * both of those know a tool by its UTCP name. Kept off `HiddenTool` so the
+ * owner-facing payload stays exactly what its surfaces declare.
+ */
+export interface ScreenedHiddenTool extends HiddenTool {
+  /** The UTCP name (`<manual>.<server>.<tool>`) the tool repository knows it by. */
+  utcpName: string;
+}
+
+/**
+ * How many schema verdicts to remember. Each is a hash and a verdict, so the
+ * cap is about a deployment that edits servers all day rather than about size;
+ * past it the whole table is cleared instead of evicted entry by entry, since
+ * the next load simply re-checks.
+ */
+const MAX_REMEMBERED_SCHEMAS = 5000;
+
+/** How many callers' pictures to hold at once — see `screen` for what happens past it. Exported for the tests that fill it. */
+export const MAX_REMEMBERED_CALLERS = 2000;
+
+export class ToolSchemaGuard implements HiddenToolSource {
+  /** Verdict per distinct schema: `null` means valid, so `undefined` means unchecked. */
+  private readonly verdicts = new Map<string, SchemaDefect | null>();
+  /**
+   * The findings, per CALLER and then per manual by catalog name.
+   *
+   * Keyed by caller because that is what a load is: discovery runs on the
+   * requesting user's own connection to the server, and two callers can be
+   * shown different tools by the same server. A single table keyed by manual
+   * would let one caller's load erase another's finding — the owner page would
+   * then show a defect from whichever request happened to be last, or none at
+   * all. Keyed by caller, a load replaces only what that caller can see, and
+   * `hiddenFor` reports the union, since the finding is about the server.
+   */
+  private readonly hidden = new Map<string, Map<string, ScreenedHiddenTool[]>>();
+  /** The newest load whose picture has been applied, per caller — see {@link beginLoad}. */
+  private readonly applied = new Map<string, number>();
+  /** Hands out {@link beginLoad} tickets; monotonic for the life of the process. */
+  private loads = 0;
+
+  /** `check` is injected only by tests, to observe how often the check runs. */
+  constructor(private readonly check: (schema: unknown) => SchemaDefect | null = inputSchemaDefect) {}
+
+  /**
+   * A ticket for a load that is ABOUT TO READ a server's tools, to be handed
+   * back to {@link screen} with what it found.
+   *
+   * Requests overlap: a caller's surface is rebuilt on every one of them, and
+   * two can be dialling the same server at once. Without an order, a load that
+   * started while a schema was still broken could land after the load that saw
+   * it corrected, and put the marker back on a tool that is fine — until some
+   * later request happened to clear it again. The ticket is taken BEFORE the
+   * read, so it ranks loads by the freshness of what they saw, and `screen`
+   * ignores a picture older than the one already applied.
+   */
+  beginLoad(): number {
+    this.loads += 1;
+    return this.loads;
+  }
+
+  /**
+   * Screen everything one caller's request just loaded — every manual on their
+   * surface, with the tools that manual advertised — and replace that caller's
+   * whole picture. Returns the tools to keep off the agent surfaces, keyed by
+   * UTCP name.
+   *
+   * WHOLE is the point, and why this takes every manual rather than one. A
+   * manual whose group is EMPTY has nothing hidden: its server dropped the
+   * offending tool, or it failed to attach at all and its tools are not loaded.
+   * A manual absent from `groups` is no longer on this caller's surface. Either
+   * way the marker goes, with nothing to clear by hand — and nothing claims a
+   * tool is hidden for a schema this process can no longer see.
+   *
+   * `loadId` comes from {@link beginLoad}, taken before the tools were read. A
+   * load that is already out of date still gets its own answer — the request
+   * that ran it must not offer a tool it has just judged invalid — but it does
+   * not write that answer into what everyone else reads.
+   */
+  screen(
+    userId: string,
+    loadId: number,
+    groups: ReadonlyMap<string, readonly ScreenedTool[]>,
+  ): Map<string, ScreenedHiddenTool> {
+    const found = new Map<string, ScreenedHiddenTool>();
+    const picture = new Map<string, ScreenedHiddenTool[]>();
+    for (const [manual, tools] of groups) {
+      const ofManual: ScreenedHiddenTool[] = [];
+      for (const tool of tools) {
+        const defect = this.verdict(tool.inputSchema);
+        if (!defect) continue;
+        const hidden: ScreenedHiddenTool = {
+          manual,
+          name: tool.mcpName,
+          utcpName: tool.utcpName,
+          path: defect.path,
+          reason: defect.reason,
+          marker: schemaDefectMarker(defect),
+        };
+        found.set(tool.utcpName, hidden);
+        ofManual.push(hidden);
+      }
+      if (ofManual.length > 0) picture.set(manual, ofManual);
+    }
+    // Stale: a load that read the server earlier than one already applied for
+    // THIS caller. Its own answer stands, the shared picture does not move.
+    //
+    // Per caller, and nothing wider. An evicted caller's watermark goes with
+    // their picture, and that loses nothing: once nothing of theirs is held,
+    // whichever of their loads lands next is the newest picture this process
+    // has of them, and it restores the watermark that rejects any older one
+    // landing after it. A floor shared across callers would instead reject
+    // some OTHER caller's newest load for having begun before an unrelated
+    // eviction, and the owner's page would miss that caller's finding.
+    if (loadId < (this.applied.get(userId) ?? 0)) return found;
+    // Not about size — each entry is a handful of strings — but about a
+    // deployment with many callers never growing these without bound. Evicted
+    // one caller at a time, the longest unseen first, so every other caller's
+    // findings stay on the owner's page; the next load of the evicted surface
+    // puts its own back. (Re-inserted on every load, so a Map's insertion
+    // order is the order of last sight.)
+    while (this.applied.size >= MAX_REMEMBERED_CALLERS && !this.applied.has(userId)) {
+      const oldest = this.applied.keys().next().value as string;
+      this.applied.delete(oldest);
+      this.hidden.delete(oldest);
+    }
+    this.applied.delete(userId);
+    this.applied.set(userId, loadId);
+    if (picture.size > 0) this.hidden.set(userId, picture);
+    else this.hidden.delete(userId);
+    return found;
+  }
+
+  hiddenFor(manual: string): HiddenTool[] {
+    const union = new Map<string, HiddenTool>();
+    for (const picture of this.hidden.values()) {
+      for (const { manual: of, name, path, reason, marker } of picture.get(manual) ?? []) {
+        // One entry per distinct defect: two callers shown the same broken tool
+        // have found one thing, and its owner should read it once. Projected to
+        // the owner-facing shape, so nothing of the loading side rides along.
+        union.set(`${name}\u0000${path}\u0000${reason}`, { manual: of, name, path, reason, marker });
+      }
+    }
+    return [...union.values()];
+  }
+
+  /** The check itself, once per distinct schema. */
+  private verdict(schema: unknown): SchemaDefect | null {
+    const key = createHash('sha1').update(JSON.stringify(schema) ?? 'undefined').digest('hex');
+    const remembered = this.verdicts.get(key);
+    if (remembered !== undefined) return remembered;
+    const defect = this.check(schema);
+    if (this.verdicts.size >= MAX_REMEMBERED_SCHEMAS) this.verdicts.clear();
+    this.verdicts.set(key, defect);
+    return defect;
+  }
+}

package/src/modules/plugins/__tests__/plugins.tools.test.ts

@@ -6,7 +6,11 @@ import { InternalTokenService } from '../../tool-auth/internal-token.service.js'
 import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
 import { keyOrSessionAuth } from '../../tool-auth/key-or-session.middleware.js';
 import { createAuthMiddleware } from '../../auth/auth.middleware.js';
-import { registerPluginsTools, CREATE_PLUGIN, MY_PLUGIN } from '../plugins.tools.js';
+import { DEFAULT_KB_LAYOUT, validateKbLayout } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength } from '../../tool-registry/description-length.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { registerPluginsTools, CREATE_PLUGIN, myPluginDef, myPluginDescription } from '../plugins.tools.js';
 import { createPluginCreationRoutes } from '../plugins.routes.js';
 import { PluginProvisionError } from '../plugin-provision.service.js';
 
@@ -20,18 +24,164 @@ import { PluginProvisionError } from '../plugin-provision.service.js';
 
 const ALICE = { id: 'user-alice', email: 'alice@x.com', name: 'Alice' };
 
+/** `my_plugin` as the catalog lists it for `layout`, on the external surface. */
+async function listedMyPlugin(layout = DEFAULT_KB_LAYOUT): Promise<{ description: string }> {
+  const registry = new ToolRegistry();
+  registerPluginsTools(registry, testKbContext({ layout }));
+  const listed = (await registry.listExternal({ userEmail: ALICE.email })).find((t) => t.name === 'my_plugin');
+  expect(listed, 'my_plugin is not in the external catalog').toBeDefined();
+  return listed as { description: string };
+}
+
+/** The rule, in the words a client must be handed before any cut. */
+const RULE = [
+  'personal plugin',
+  'their own skills and tools',
+  'they go under the knowledge root',
+  'ask where under the knowledge root',
+  'restricted so only they can read it',
+  'never write it here, even if asked',
+];
+
 describe('the tool definitions', () => {
   it('describe the creation endpoints, and reach every surface', async () => {
     expect((CREATE_PLUGIN.tool_call_template as { url: string }).url).toBe('${API_URL}/api/plugins');
-    expect((MY_PLUGIN.tool_call_template as { url: string }).url).toBe('${API_URL}/api/plugins/personal');
+    expect((myPluginDef(DEFAULT_KB_LAYOUT).tool_call_template as { url: string }).url).toBe(
+      '${API_URL}/api/plugins/personal',
+    );
     const registry = new ToolRegistry();
-    registerPluginsTools(registry);
+    registerPluginsTools(registry, testKbContext());
     for (const tools of [await registry.listExternal({ userEmail: ALICE.email }), await registry.listInternal({ userEmail: ALICE.email })]) {
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(['my_plugin', 'create_plugin']));
     }
   });
 });
 
+/**
+ * What `my_plugin` TELLS an agent. A personal plugin holds its owner's skills
+ * and tools; nothing under the plugins root is in the knowledge graph and a
+ * personal plugin is readable only by its owner, so a note filed there is
+ * never found as knowledge again. The old description opened by calling the
+ * folder "their personal space in the knowledge base", which read as an
+ * invitation to file one. Pinned here because the text IS the change: nothing
+ * refuses such a write, before or after (see the last test in this block).
+ */
+describe('what my_plugin tells an agent about the personal plugin', () => {
+  it('states the rule, naming this deployment\'s knowledge root', async () => {
+    const { description } = await listedMyPlugin();
+    expect(description).toContain("The caller's personal plugin: their own skills and tools");
+    expect(description).toContain('Notes, knowledge and other documents do NOT go here; they go under the knowledge root.');
+    expect(description).toContain('The knowledge root here is `KnowledgeBase/`.');
+    // A private request gets a QUESTION and the restrictable folder, never the
+    // personal plugin — not even when the user asks for it outright.
+    expect(description).toContain('ask where under the knowledge root it should go');
+    expect(description).toContain('restricted so only they can read it');
+    expect(description).toContain('never write it here, even if asked');
+    // The name the app shows, and none of the three phrases that sent agents here.
+    for (const retired of ['personal space', 'private space', 'own space']) {
+      expect(description, retired).not.toContain(retired);
+    }
+  });
+
+  it('names a RENAMED knowledge root, and never the default one', async () => {
+    const renamed = { knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' };
+    const { description } = await listedMyPlugin(renamed);
+    expect(description).toContain('The knowledge root here is `Docs/`.');
+    expect(description).not.toContain('KnowledgeBase');
+  });
+
+  /**
+   * The save that completes first-run setup applies the names the admin just
+   * chose IN THAT REQUEST, with no restart, so a description built once at
+   * registration would go on naming a folder the deployment no longer has.
+   * Rewritten in place, which is why both surfaces see it: they hold the same
+   * object.
+   */
+  it('follows a layout applied after registration, on both surfaces', async () => {
+    const registry = new ToolRegistry();
+    const kb = testKbContext();
+    registerPluginsTools(registry, kb);
+    kb.applyLayout({ knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' });
+    for (const tools of [await registry.listExternal(), await registry.listInternal()]) {
+      const description = tools.find((t) => t.name === 'my_plugin')!.description!;
+      expect(description).toContain('The knowledge root here is `Docs/`.');
+      expect(description).not.toContain('KnowledgeBase');
+    }
+  });
+
+  /**
+   * claude.ai cuts a tool description near `CLIENT_SHORT_CUT` characters, and
+   * it counts from the guide-first sentence the registry puts in front of every
+   * listed tool. So the rule has to be inside that window of the text A CLIENT
+   * IS HANDED, with the `skillsDir` mechanics — which the guide states in full
+   * anyway — as what a short client loses instead.
+   */
+  it(`states the whole rule within the first ${CLIENT_SHORT_CUT} characters a client is handed`, async () => {
+    for (const layout of [DEFAULT_KB_LAYOUT, { knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' }]) {
+      const { description } = await listedMyPlugin(layout);
+      expect(description.startsWith(`${GUIDE_FIRST_SENTENCE} `), 'the opener is counted too').toBe(true);
+      const cut = description.slice(0, CLIENT_SHORT_CUT);
+      const root = layout.knowledgeBaseDir;
+      for (const phrase of [...RULE, `The knowledge root here is \`${root}/\`.`]) {
+        expect(cut, `"${phrase}" falls past the ${CLIENT_SHORT_CUT}-character cut`).toContain(phrase);
+      }
+    }
+  });
+
+  /**
+   * A folder name may run to 255 bytes. The root is named once, after the rule,
+   * so even the longest name a deployment can choose leaves the whole rule
+   * inside the cut and the whole text inside the cap.
+   */
+  it('keeps the rule inside the cut, and the text inside the cap, for the longest root name', async () => {
+    const longest = { knowledgeBaseDir: 'K'.repeat(255), skillsDir: 'Skills', pluginsDir: 'Plugins' };
+    expect(validateKbLayout(longest), 'the name is one a deployment may choose').toBeNull();
+    const listed = await listedMyPlugin(longest);
+    const cut = listed.description.slice(0, CLIENT_SHORT_CUT);
+    for (const phrase of RULE) {
+      expect(cut, `"${phrase}" falls past the ${CLIENT_SHORT_CUT}-character cut`).toContain(phrase);
+    }
+    expect(listed.description).toContain(`The knowledge root here is \`${longest.knowledgeBaseDir}/\`.`);
+    expect(clientVisibleLength({ name: 'my_plugin', description: listed.description })).toBeLessThanOrEqual(
+      TOOL_DESCRIPTION_CAP,
+    );
+  });
+
+  /** Only the description changed: the call an agent makes is the call it made. */
+  it('keeps its endpoint, inputs, outputs and tags exactly as they were', () => {
+    const def = myPluginDef(DEFAULT_KB_LAYOUT);
+    expect((def.tool_call_template as { url: string; http_method: string }).url).toBe('${API_URL}/api/plugins/personal');
+    expect((def.tool_call_template as { http_method: string }).http_method).toBe('POST');
+    // The flat inputs are wrapped under `body` by `toolDef`; `my_plugin` takes none.
+    expect(def.inputs).toEqual({
+      type: 'object',
+      properties: { body: { type: 'object', properties: {}, additionalProperties: false } },
+      required: ['body'],
+      additionalProperties: false,
+    });
+    expect(Object.keys((def.outputs as { properties: Record<string, unknown> }).properties)).toEqual([
+      'path',
+      'skillsDir',
+      'folder',
+      'name',
+      'displayName',
+      'created',
+    ]);
+    expect(def.tags).toEqual(['plugins', 'skills', 'write']);
+    // Byte-identical on every layout but the description.
+    const renamed = myPluginDef({ knowledgeBaseDir: 'Docs', skillsDir: 'Abilities', pluginsDir: 'Extensions' });
+    expect({ ...renamed, description: '' }).toEqual({ ...def, description: '' });
+    expect(renamed.description).not.toBe(def.description);
+  });
+
+  /** A layout given with untrimmed names is read the way every other reader reads it. */
+  it('reads the layout through the same resolver the rest of the platform uses', () => {
+    expect(myPluginDescription({ knowledgeBaseDir: '  Docs  ', skillsDir: 'Skills', pluginsDir: 'Plugins' })).toContain(
+      '`Docs/`',
+    );
+  });
+});
+
 describe('the creation endpoints behind the key-or-session gate', () => {
   const ensurePersonalPlugin = vi.fn(async (user: { id: string }) => ({
     folder: `personal-${user.id}`,
@@ -112,7 +262,7 @@ describe('the creation endpoints behind the key-or-session gate', () => {
     expect(createPlugin).toHaveBeenLastCalledWith(expect.objectContaining({ id: ALICE.id }), 'Ops', undefined);
   });
 
-  it("my_plugin's endpoint ensures the caller's own space for a key holder", async () => {
+  it("my_plugin's endpoint ensures the caller's own personal plugin for a key holder", async () => {
     const base = await start();
     const res = await post(base, '/api/plugins/personal', {}, 'bevel_alice');
     expect(res.status).toBe(200);

package/src/modules/plugins/plugins.tools.ts

@@ -1,3 +1,5 @@
+import { resolveKbLayout, type KbLayout } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
 
@@ -21,9 +23,24 @@ import { toolDef } from '../tool-helpers/tool-def.js';
  * agent exactly as for a person; a refusal comes back as the endpoint's own
  * 4xx with its message.
  */
-export function registerPluginsTools(registry: IToolRegistry): void {
-  registry.registerExternalTool(MY_PLUGIN);
-  registry.registerInternalTool(MY_PLUGIN);
+export function registerPluginsTools(registry: IToolRegistry, kb: KbContext): void {
+  // ONE object on both surfaces, so the rewrite below reaches both of them.
+  // The registry holds this object, and re-registering under the same name
+  // would throw as a duplicate.
+  const myPlugin = myPluginDef(kb.layout);
+  registry.registerExternalTool(myPlugin);
+  registry.registerInternalTool(myPlugin);
+  /**
+   * `my_plugin`'s description NAMES the knowledge root, so its text has to
+   * follow the layout: the save that completes first-run setup applies the
+   * names the admin just chose in that same request, without a restart, and a
+   * description built once at registration would go on sending notes to a
+   * folder this deployment no longer has. Rewritten in place, exactly as the
+   * workspace tools' descriptions are (see `workspace.tools.ts`).
+   */
+  kb.onLayoutApplied(() => {
+    myPlugin.description = myPluginDescription(kb.layout);
+  });
   registry.registerExternalTool(CREATE_PLUGIN);
   registry.registerInternalTool(CREATE_PLUGIN);
 }
@@ -41,21 +58,64 @@ const PROVISIONED_OUTPUT = {
   },
 } as const;
 
-export const MY_PLUGIN: UtcpTool = toolDef({
-  name: 'my_plugin',
-  description:
-    "The caller's own private plugin — their personal space in the knowledge base, created on first use. " +
+/**
+ * What an agent reads about the personal plugin, for the layout in effect.
+ *
+ * THE RULE COMES FIRST, and the order is the substance of it rather than a
+ * matter of style. A personal plugin holds its owner's skills and tools;
+ * nothing under the plugins root is part of the knowledge graph, and a
+ * personal plugin is readable only by its owner — so a note filed there is
+ * never found as knowledge again, by anyone, including its author's next
+ * agent. Agents asked to "save this for me" were reading the old opening,
+ * "their personal space in the knowledge base", as an invitation to do
+ * precisely that.
+ *
+ * Stated ahead of the mechanics of writing a skill, not after them, because
+ * claude.ai cuts a tool description near `CLIENT_SHORT_CUT` characters (see
+ * `tool-registry/description-length.ts`) counted from the guide-first sentence
+ * the registry puts in front of every listed tool. What survives that cut is
+ * decided by ORDER, so the rule sits inside it and the `skillsDir` detail —
+ * which the guide states in full anyway — is what a short client loses.
+ * The root is named ONCE, after the rule rather than inside it: a folder name
+ * may run to 255 bytes, and repeated within the rule it could push the rule
+ * itself past the cut and the whole text past `TOOL_DESCRIPTION_CAP`.
+ * `plugins.tools.test.ts` pins that placement rather than trusting this note.
+ *
+ * It REFUSES nothing. The write gate accepts every file in a personal plugin
+ * exactly as it did before; this text is the whole of the change.
+ */
+export function myPluginDescription(layout: KbLayout): string {
+  const knowledge = `\`${resolveKbLayout(layout).knowledgeBaseDir}/\``;
+  return (
+    "The caller's personal plugin: their own skills and tools, created on first use. " +
+    'Notes, knowledge and other documents do NOT go here; they go under the knowledge root. ' +
+    'For something the user wants kept private, ask where under the knowledge root it should go and say a ' +
+    'folder there can be restricted so only they can read it; never write it here, even if asked. ' +
+    `The knowledge root here is ${knowledge}. ` +
     'Returns its folder and where skills go inside it (`skillsDir`); write a skill there as ' +
     '`<skillsDir>/<skill-name>/SKILL.md` with the file tools, opening with the Agent Skills frontmatter ' +
     '(`name`, `description`, and `metadata.version` such as `"1.0.0"`). Readable only by its owner — not even admins — and ' +
-    'never listed as a shared plugin. Idempotent: calling it again returns the same folder.',
-  path: '/api/plugins/personal',
-  inputs: { type: 'object', properties: {}, additionalProperties: false },
-  outputs: PROVISIONED_OUTPUT,
-  // `write`: both make folders and commit — a read-scoped caller's manual
-  // must not advertise them (see `isWriteTool` in the manual routes).
-  tags: ['plugins', 'skills', 'write'],
-});
+    'never listed as a shared plugin. Idempotent: calling it again returns the same folder.'
+  );
+}
+
+/**
+ * The `my_plugin` definition for `layout`. Everything but the description is
+ * the same on every deployment and byte-identical to what it has always been:
+ * the same endpoint, the same (empty) inputs, the same outputs, the same tags.
+ */
+export function myPluginDef(layout: KbLayout): UtcpTool {
+  return toolDef({
+    name: 'my_plugin',
+    description: myPluginDescription(layout),
+    path: '/api/plugins/personal',
+    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    outputs: PROVISIONED_OUTPUT,
+    // `write`: both make folders and commit — a read-scoped caller's manual
+    // must not advertise them (see `isWriteTool` in the manual routes).
+    tags: ['plugins', 'skills', 'write'],
+  });
+}
 
 export const CREATE_PLUGIN: UtcpTool = toolDef({
   name: 'create_plugin',

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

@@ -191,8 +191,6 @@ describe('DeploymentSettingsService — KB layout', () => {
       pluginsDir: 'Plugins',
       agentsFile: 'AGENTS.md',
     });
-    // The pointer is on until someone says otherwise.
-    expect(settings.resolveAgentsFileLink()).toBe(true);
   });
 
   /**
@@ -225,9 +223,9 @@ describe('DeploymentSettingsService — KB layout', () => {
   it('ignores the environment for the four layout names', async () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);
-    await settings.save({ skillsDir: 'skills', pluginsDir: 'plugins', agentsFile: 'HEXIS.md' }, null);
+    await settings.save({ skillsDir: 'skills', pluginsDir: 'plugins' }, null);
     process.env.KB_SKILLS_DIR = 'capabilities';
-    expect(settings.resolveKbLayout()).toMatchObject({ skillsDir: 'skills', agentsFile: 'HEXIS.md' });
+    expect(settings.resolveKbLayout()).toMatchObject({ skillsDir: 'skills' });
     expect(settings.sourceOf('skillsDir')).toBe('stored');
     // Not locked: the field stays editable in the app, and a save of it is
     // accepted rather than refused as 'set by the environment'.
@@ -284,68 +282,41 @@ describe('DeploymentSettingsService — KB layout', () => {
   });
 
   /**
-   * The guide's file name is saved beside the folders and judged with them:
-   * the four must differ, and a name that is not one markdown file is refused
-   * with the rule it broke.
+   * The guide's name was a setting while the guide was written to disk. It is
+   * gone: the setup screen no longer offers it, a save naming it is refused
+   * as unknown, and the guide is read as `AGENTS.md` on every deployment
+   * whatever a deployment saved before.
    */
-  it('refuses a guide name that is not one markdown file of its own', async () => {
-    const { db } = makeDb();
-    const settings = new DeploymentSettingsService(db, ENC_KEY);
-    for (const bad of ['guides/HEXIS.md', 'HEXIS.txt', 'CLAUDE.md', 'access.md', 'roles.yaml']) {
-      await expect(settings.save({ agentsFile: bad }, null)).rejects.toBeInstanceOf(
-        SettingsValidationError,
-      );
-    }
-    await expect(settings.save({ agentsFile: 'HEXIS.md' }, null)).resolves.toBeTruthy();
-  });
-
-  it('refuses a guide named after a root folder, from either side of the pair', async () => {
-    const { db } = makeDb();
-    const settings = new DeploymentSettingsService(db, ENC_KEY);
-    // The plugins folder already in effect, named by the guide alone.
-    await settings.save({ pluginsDir: 'Guide.md' }, null);
-    await expect(settings.save({ agentsFile: 'guide.md' }, null)).rejects.toBeInstanceOf(
-      SettingsValidationError,
-    );
-    // And the other way round, in one batch.
-    await expect(
-      settings.save({ agentsFile: 'HEXIS.md', skillsDir: 'hexis.md' }, null),
-    ).rejects.toBeInstanceOf(SettingsValidationError);
-  });
-
-  it('marks the guide name and its pointer setting as restart-to-apply', async () => {
-    const { db } = makeDb();
+  it('knows no guide name any more: a save naming one is refused, and the layout always says AGENTS.md', async () => {
+    const { db, rows } = makeDb();
+    // The row a deployment saved while the setting existed is still in its
+    // database. It is loaded like any other row, and changes nothing.
+    rows.push({ key: 'agentsFile', value: 'HEXIS.md', encrypted: false });
     const settings = new DeploymentSettingsService(db, ENC_KEY);
-    expect((await settings.save({ agentsFile: 'HEXIS.md' }, null)).restartKeys).toContain('agentsFile');
-    expect((await settings.save({ agentsFileLink: 'false' }, null)).restartKeys).toContain(
-      'agentsFileLink',
-    );
-    expect(settings.resolveAgentsFileLink()).toBe(false);
+    await settings.load();
+    expect(settings.resolveKbLayout().agentsFile).toBe('AGENTS.md');
+    await expect(settings.save({ agentsFile: 'HEXIS.md' }, null)).rejects.toMatchObject({
+      problems: { agentsFile: 'Unknown setting.' },
+    });
+    await expect(settings.save({ agentsFile: 'HEXIS.md' }, null, 'deployment')).rejects.toMatchObject({
+      problems: { agentsFile: 'Unknown setting.' },
+    });
+    expect(settings.resolveKbLayout().agentsFile).toBe('AGENTS.md');
+    expect(settings.describe().map((s) => s.key)).not.toContain('agentsFile');
   });
 
   /**
    * A restart is owed for a CHANGE, and saving what a deployment is already
-   * running on is not one. Both of these settings mean something while unset —
-   * the guide is `AGENTS.md`, the pointer is on — so the first save of that
-   * same answer changes nothing the process would pick up at a restart.
+   * running on is not one. A root name means something while unset — the
+   * default — so the first save of that same answer changes nothing the
+   * process would pick up at a restart.
    */
   it('owes no restart for saving the value an unset setting already meant', async () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);
-    // The checkbox arrives ticked, and ticked is what an unset one already is.
-    expect((await settings.save({ agentsFileLink: 'true' }, null)).restartKeys).not.toContain(
-      'agentsFileLink',
-    );
-    expect((await settings.save({ agentsFile: 'AGENTS.md' }, null)).restartKeys).not.toContain(
-      'agentsFile',
-    );
     expect((await settings.save({ skillsDir: 'Skills' }, null)).restartKeys).not.toContain('skillsDir');
-    // And the setting still reads as it did.
-    expect(settings.resolveAgentsFileLink()).toBe(true);
-    // Turning it off from there IS a change, and still reports one.
-    expect((await settings.save({ agentsFileLink: 'false' }, null)).restartKeys).toContain(
-      'agentsFileLink',
-    );
+    // Renaming it from there IS a change, and still reports one.
+    expect((await settings.save({ skillsDir: 'Abilities' }, null)).restartKeys).toContain('skillsDir');
   });
 
   /**