@bevel-software/platform-core-backend 0.34.0 → 0.35.0

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

@@ -59,6 +59,7 @@ import {
   type ToolProbeTarget,
   type ToolVariableScope,
   type ToolVariableOAuth,
+  type LiveDeclaration,
 } from './tool-manuals.contract.js';
 
 const CACHE_TTL_MS = 60_000;
@@ -182,6 +183,19 @@ export function describeManualFault(err: unknown): string {
 interface ScanResult {
   manuals: ToolManualDescriptor[];
   invalid: InvalidToolManual[];
+  /**
+   * Every manual the parse refused whose file still says which manual it is,
+   * by slug, with the reason. Not a listing surface (`invalid` is that, by
+   * path): it lets a sign-in started on a refused declaration answer why,
+   * where the slug alone would otherwise find nothing.
+   */
+  refused: RefusedManual[];
+}
+
+interface RefusedManual {
+  slug: string;
+  path: string;
+  reason: string;
 }
 
 /**
@@ -191,7 +205,7 @@ interface ScanResult {
  * convention instance is one push away from every empty scan in the process
  * inheriting another's contents.
  */
-const emptyScan = (): ScanResult => ({ manuals: [], invalid: [] });
+const emptyScan = (): ScanResult => ({ manuals: [], invalid: [], refused: [] });
 
 const manualSerializer = new UtcpManualSerializer();
 const callTemplateSerializer = new CallTemplateSerializer();
@@ -209,8 +223,8 @@ export interface McpAuthDiscoveryPort {
   /**
    * The sign-in endpoints for an OWNER-REGISTERED client: the same metadata
    * walk as `statusFor`, stopping short of dynamic registration — the manual
-   * already names its `clientId`. Nothing is persisted; the owner's
-   * client-secret save pins the completed provider. Optional so a port that
+   * already names its `clientId`. Nothing is persisted; every sign-in start
+   * completes the declaration afresh (`liveDeclaration`). Optional so a port that
    * only knows the zero-config path still satisfies the interface.
    */
   providerForDeclaredClient?(manualName: string, mcpUrl: string, clientId: string): Promise<McpAuthDiscoveryResult>;
@@ -342,6 +356,38 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
+  async liveDeclaration(
+    userEmail: string,
+    slug: string,
+    varName: string,
+  ): Promise<LiveDeclaration | null> {
+    // The disk walk the catalog's scan is built from, run afresh and never
+    // cached: a sign-in must follow the file as it is, and the catalog's scan
+    // can be a refresh behind it. The whole walk rather than the one file, so
+    // the descriptor comes out of exactly the parse, plugin discovery and
+    // namespace dedup the catalog applies — a sign-in start is rare and
+    // interactive, and a second, single-file reading of the same files is a
+    // second place for those rules to drift. A workspace that cannot be opened
+    // is an error here, never an empty answer: "no sign-in declared" would be
+    // the wrong diagnosis for a server that could not read its files.
+    const { manuals, refused } = await this.readableBy(await this.scanDisk(undefined, 'throw'), userEmail);
+    const m = manuals.find((x) => x.slug === slug);
+    if (!m) {
+      // The file is there and says it is this manual, but the parse refused
+      // it — e.g. its sign-in names an http:// or private token endpoint. That
+      // reason is the answer; "not found" would hide the one thing to fix.
+      const r = refused.find((x) => x.slug === slug);
+      return r ? { refused: r.reason } : null;
+    }
+    const variable = (m.variables ?? []).find((v) => v.name === varName);
+    // Completed by the catalog's own decoration, on this one fresh descriptor.
+    // Only when THIS variable is a sign-in: then the manual has a declared one,
+    // so the pass completes its endpoints from the server's metadata and never
+    // probes for (or registers) a zero-config client.
+    if (variable?.oauth) await this.decorateMcpOAuth([m]);
+    return { manual: toSummary(m), ...(variable ? { variable } : {}) };
+  }
+
   async listLocalOnly(userEmail: string, within?: ConnectorScope): Promise<{ slug: string; name: string; path: string }[]> {
     const manuals = await this.accessibleManuals(userEmail, within);
     return manuals.filter((m) => m.remote === false).map((m) => ({ slug: m.slug, name: m.name, path: m.path }));
@@ -616,11 +662,16 @@ export class ToolManualService implements IToolManualService {
    * in. Absent, the answer is the caller's whole readable catalog.
    */
   private async accessibleScan(userEmail: string, within?: ConnectorScope): Promise<ScanResult> {
-    const { manuals, invalid } = await this.scan();
-    if (manuals.length === 0 && invalid.length === 0) return emptyScan();
+    return this.readableBy(await this.scan(), userEmail, within);
+  }
+
+  /** A scan cut to what this caller may read — see {@link accessibleScan}. */
+  private async readableBy(scan: ScanResult, userEmail: string, within?: ConnectorScope): Promise<ScanResult> {
+    const { manuals, invalid, refused } = scan;
+    if (manuals.length === 0 && invalid.length === 0 && refused.length === 0) return emptyScan();
     const wsId = this.kb.defaultWorkspaceId();
     const allowed = await this.accessControl.canReadBatch(wsId, userEmail, [
-      ...new Set([...manuals.map((m) => m.path), ...invalid.map((i) => i.path)]),
+      ...new Set([...manuals.map((m) => m.path), ...invalid.map((i) => i.path), ...refused.map((r) => r.path)]),
     ]);
     // Fail closed: keep an entry only on an explicit `true` verdict (a missing
     // entry is treated as denied, matching the KB's default-deny read model).
@@ -631,6 +682,7 @@ export class ToolManualService implements IToolManualService {
     return {
       manuals: manuals.filter((m) => inScope(m.path)),
       invalid: invalid.filter((i) => inScope(i.path)),
+      refused: refused.filter((r) => inScope(r.path)),
     };
   }
 
@@ -655,14 +707,14 @@ export class ToolManualService implements IToolManualService {
     // See `TtlCache.begin`: taken before the read so an `invalidate()` that
     // lands mid-scan discards this result instead of being overwritten by it.
     const token = this.cache.begin();
-    const { manuals, invalid } = await this.scanDisk();
+    const scanned = await this.scanDisk();
+    const { manuals } = scanned;
     await this.decorateMcpOAuth(manuals);
     // AFTER the oauth decoration, so an injected `${MCP_OAUTH}` header ref is
     // already declared and isn't re-surfaced as a bare admin key.
     for (const m of manuals) this.surfaceReferencedVariables(m);
-    const result = { manuals, invalid };
-    this.cache.set(result, token);
-    return result;
+    this.cache.set(scanned, token);
+    return scanned;
   }
 
   /**
@@ -833,11 +885,12 @@ export class ToolManualService implements IToolManualService {
    * (the owner registered an app with a provider that offers no dynamic
    * registration — HubSpot, Google) gets its endpoints, PKCE and resource
    * indicator from the server's own OAuth metadata, exactly as the zero-config
-   * path would. The descriptor is completed IN MEMORY: the client-secret route
-   * reads the completed declaration and pins it with the secret, so nothing
-   * here persists. When the metadata can't be had, the declaration stays
-   * incomplete and `setup.reason` says so — the secret route then refuses
-   * with the same reason instead of pinning a provider with no endpoints.
+   * path would. The descriptor is completed IN MEMORY, for the catalog's scan
+   * and for every sign-in start (`liveDeclaration`) alike, so nothing here
+   * persists. When the metadata can't be had, the declaration stays
+   * incomplete and `setup.reason` says so — the client-secret save and the
+   * sign-in start then refuse with the same reason instead of running a
+   * provider with no endpoints.
    */
   private async completeDeclaredOAuth(
     discovery: McpAuthDiscoveryPort,
@@ -896,11 +949,22 @@ export class ToolManualService implements IToolManualService {
    * calls: a refusal lives only in the scan it came from, so a fixed file is a
    * valid manual on the very next scan.
    */
-  private async scanDisk(branch: string = this.kb.defaultBranch): Promise<ScanResult> {
+  private async scanDisk(
+    branch: string = this.kb.defaultBranch,
+    /**
+     * What a workspace that cannot be opened means. For the catalog, an empty
+     * scan: a listing surface answers "nothing released" and the next scan
+     * tries again. For a sign-in start (`liveDeclaration`), the error itself:
+     * an empty answer there would read as "this tool has no sign-in", a
+     * misconfiguration, when the server could not read its files at all.
+     */
+    workspaceFailure: 'empty' | 'throw' = 'empty',
+  ): Promise<ScanResult> {
     let wsId: string;
     try {
       wsId = (await this.workspaceService.getOrCreateForBranch(branch)).id;
-    } catch {
+    } catch (err) {
+      if (workspaceFailure === 'throw') throw err;
       return emptyScan();
     }
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
@@ -921,6 +985,7 @@ export class ToolManualService implements IToolManualService {
     // The plugins (and their mcp.json text) come from the configured source, so
     // a dialect that expands servers from a registry lands here unchanged.
     const parsed: ToolManualDescriptor[] = [];
+    const refused: RefusedManual[] = [];
     const discovered = await this.source.discover(kbRoot);
     for (const plugin of discovered.plugins) {
       if (plugin.mcpJsonText === null) continue; // no servers is the common case, not an error
@@ -929,7 +994,9 @@ export class ToolManualService implements IToolManualService {
       // (a URL, a header, an added or dropped server, a `local: true` flip)
       // moves every server's digest — which is correct, if slightly generous.
       const from = sourceDigest(plugin.mcpJsonText + '\u0000' + (plugin.manifestText ?? ''));
-      for (const d of descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText, layout)) {
+      const onRefused = (slug: string, reason: string, path: string) =>
+        refused.push({ slug, path, reason: describeManualFault(reason) });
+      for (const d of descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText, layout, onRefused)) {
         d.sourceRevision = from;
         parsed.push(d);
       }
@@ -965,6 +1032,8 @@ export class ToolManualService implements IToolManualService {
         // outage from where the author stands: the tool is gone from every
         // listing, with nothing anywhere saying which file or why.
         invalid.push({ path: f.rel, reason: describeManualFault(err) });
+        const slug = refusedToolManualName(baseName(f.rel), content);
+        if (slug !== null) refused.push({ slug, path: f.rel, reason: describeManualFault(err) });
         continue;
       }
       // The route slug IS the id (unique after dedup below, snake_case → URL-safe),
@@ -1013,7 +1082,7 @@ export class ToolManualService implements IToolManualService {
     // draft workspace, and a draft's half-written `.tool` is not news about the
     // served catalog — it would also flap the log every time an agent saves.
     if (branch === this.kb.defaultBranch) this.logInvalidOnChange(invalid);
-    return { manuals, invalid };
+    return { manuals, invalid, refused };
   }
 }
 
@@ -1125,6 +1194,54 @@ function manualName(raw: string): string {
   return name;
 }
 
+/**
+ * The object a `.tool` file holds: its `---` block when fenced, the whole file
+ * when not. Throws when that is not an object.
+ */
+function toolFileObject(content: string): Record<string, unknown> {
+  const fm = extractFrontmatter(content);
+  const source = fm ? fm.frontmatter : content;
+  const parsed = parseYaml(source) as unknown;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('`.tool` file must be a YAML/JSON object (in the `---` block when fenced)');
+  }
+  return parsed as Record<string, unknown>;
+}
+
+/**
+ * A `.tool`'s manual name — its UTCP namespace, and the slug the scan serves it
+ * under. An explicit `id` is used VERBATIM, so it must be lowercase snake_case
+ * (UTCP's namespace grammar). With no explicit id, fall back to `name` then the
+ * filename and sanitize (legacy behaviour — keeps existing tools' namespaces).
+ */
+function toolManualName(obj: Record<string, unknown>, provisionalSlug: string): string {
+  const explicitId = typeof obj.id === 'string' ? obj.id.trim() : '';
+  if (!explicitId) return manualName(resolveDeclaredId(obj, provisionalSlug));
+  if (!isValidId(explicitId)) {
+    // The rejected id is NOT quoted back — see `describeManualFault`: this
+    // message becomes an `invalid[].reason` on an agent transcript, a browser
+    // and a log, and `id` is a field an author can paste anything into,
+    // including the token they meant for a header. The field name plus the
+    // rule is what the author needs; the value is in front of them.
+    throw new Error('tool `id` must be lowercase snake_case (letters, digits, underscores)');
+  }
+  return explicitId;
+}
+
+/**
+ * The manual name of a `.tool` the parser REFUSED, when the file still says
+ * which manual it is — by the same rule {@link normalizeToolManual} names a
+ * manual it accepts. `null` when even that cannot be read (unparseable YAML,
+ * a malformed `id`): then nothing can claim the refusal by name.
+ */
+function refusedToolManualName(provisionalSlug: string, content: string): string | null {
+  try {
+    return toolManualName(toolFileObject(content), provisionalSlug);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Parse + normalize a `.tool` file into a descriptor. THE TOOL IS THE
  * FRONTMATTER: a fenced file's single `---` YAML block carries everything —
@@ -1148,34 +1265,9 @@ export function normalizeToolManual(
   // finds its verbs inside the fence, the id index finds `id`/`name`, and the
   // config keys live in the same object. A fence-less file is the legacy form
   // (the whole file is the object) — JSON `.tool`s can't carry fences.
-  const fm = extractFrontmatter(content);
-  const source = fm ? fm.frontmatter : content;
-  const parsed = parseYaml(source) as unknown;
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error('`.tool` file must be a YAML/JSON object (in the `---` block when fenced)');
-  }
-  const obj = parsed as Record<string, unknown>;
+  const obj = toolFileObject(content);
   const type = normalizeType(obj.type);
-
-  // Identity: an explicit `id` is used VERBATIM as the UTCP manual namespace, so
-  // it must be lowercase snake_case (UTCP's namespace grammar). With no explicit
-  // id, fall back to `name` then the filename and sanitize (legacy behaviour —
-  // keeps existing tools' namespaces).
-  const explicitId = typeof obj.id === 'string' ? obj.id.trim() : '';
-  let name: string;
-  if (explicitId) {
-    if (!isValidId(explicitId)) {
-      // The rejected id is NOT quoted back — see `describeManualFault`: this
-      // message becomes an `invalid[].reason` on an agent transcript, a browser
-      // and a log, and `id` is a field an author can paste anything into,
-      // including the token they meant for a header. The field name plus the
-      // rule is what the author needs; the value is in front of them.
-      throw new Error('tool `id` must be lowercase snake_case (letters, digits, underscores)');
-    }
-    name = explicitId;
-  } else {
-    name = manualName(resolveDeclaredId(obj, provisionalSlug));
-  }
+  const name = toolManualName(obj, provisionalSlug);
 
   // A `.tool` may not reproduce a built-in manual's UTCP namespace — that would
   // let it read the loopback creds seeded under that namespace on the agent's

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

@@ -7,18 +7,32 @@ import type { IAccessControl } from '../access/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { ConnectorScope, IToolManualService } from './tool-manuals.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
+import { userSecretGap } from '../secrets-vault/index.js';
 
 /**
  * What `list_tool_setup` needs from the secrets vault (structurally satisfied
  * by `ISecretsVaultService.statusFor`). A local port keeps this module free of
- * a secrets-vault import — the same decoupling discipline as
- * `McpAuthDiscoveryPort` in the service.
+ * the vault service — the same decoupling discipline as
+ * `McpAuthDiscoveryPort` in the service. Only the vault's pure readiness rule
+ * (`userSecretGap`, its exported contract) is imported, the one the MCP proxy
+ * hides tools by.
  */
 export interface VariableStatusPort {
   statusFor(
     userId: string,
     keys: string[],
-  ): Promise<{ key: string; adminConfigured: boolean; userConfigured: boolean; userAuthorized?: boolean }[]>;
+  ): Promise<
+    {
+      key: string;
+      adminConfigured: boolean;
+      /** What the owner's row is: a sign-in needs an `oauth` one, not a key left from when the variable was static. */
+      adminKind?: 'static' | 'oauth' | null;
+      userConfigured: boolean;
+      userAuthorized?: boolean;
+      userKind?: 'static' | 'oauth' | null;
+      grantedScopes?: string;
+    }[]
+  >;
 }
 
 /**
@@ -240,7 +254,9 @@ export function registerToolManualsTools(
         },
         note: {
           type: 'string',
-          description: 'Present when `onBranchOnly` is non-empty: what it takes for those tools to go live.',
+          description:
+            'Present when something is left to do: what it takes for the tools in `onBranchOnly` to go live, and for ' +
+            'tools that need your own value or sign-in to work.',
         },
       },
       required: ['tools', 'invalid', 'onBranchOnly'],
@@ -302,17 +318,40 @@ export function registerToolManualsTools(
         }),
       );
       const onBranchOnly = pending.map((p) => ({ ...p, branch: branch! }));
-      if (onBranchOnly.length === 0) return { tools, invalid, onBranchOnly };
-      return {
-        tools,
-        invalid,
-        onBranchOnly,
-        note:
+      const notes: string[] = [];
+      if (onBranchOnly.length > 0) {
+        notes.push(
           `${onBranchOnly.map((p) => `\`${p.name}\``).join(', ')} ${onBranchOnly.length === 1 ? 'is' : 'are'} declared on ` +
-          `\`${branch}\` only. Tools are served from \`${deps.kb.defaultBranch}\`, so ${onBranchOnly.length === 1 ? 'it stays' : 'they stay'} ` +
-          'unlisted, uncallable and without a sign-in until that branch is merged: open a change request with ' +
-          `\`open_change_request\` (target \`${deps.kb.defaultBranch}\`), then ask the user to review and merge it in the app.`,
-      };
+            `\`${branch}\` only. Tools are served from \`${deps.kb.defaultBranch}\`, so ${onBranchOnly.length === 1 ? 'it stays' : 'they stay'} ` +
+            'unlisted, uncallable and without a sign-in until that branch is merged: open a change request with ' +
+            `\`open_change_request\` (target \`${deps.kb.defaultBranch}\`), then ask the user to review and merge it in the app.`,
+        );
+      }
+      // The person's own part, said where the agent is when a tool "does not work": the
+      // reconnect step is the one agents leave out (the agent-guide benchmark, 2026-10-26).
+      // By the rule the proxy hides a tool by (`userSecretGap`), so the note
+      // names every tool that is hidden for want of the caller's own value. A
+      // sign-in waits on the owner's provider setup (an OAuth admin row, not a
+      // key left from when the variable was static — the Connect page counts
+      // that setup incomplete and the sign-in start refuses it): until then
+      // there is nothing to sign in to.
+      const needYou = manuals.filter((m) =>
+        (m.variables ?? []).some((v) => {
+          if (v.scope !== 'user') return false;
+          const st = statusByKey.get(varKey(m.name, v.name));
+          const gap = userSecretGap({ oauth: v.oauth != null, oauthScopes: v.oauth?.scopes }, st);
+          return gap !== null && (v.oauth == null || (st?.adminConfigured === true && st.adminKind === 'oauth'));
+        }),
+      );
+      if (needYou.length > 0) {
+        notes.push(
+          `${needYou.map((t) => `\`${t.name}\``).join(', ')} ${needYou.length === 1 ? 'needs' : 'need'} your own value or sign-in. ` +
+            'Set it yourself on the Connect page, never in the chat; then reconnect your assistant, or start a new chat, ' +
+            'so the tool is listed.',
+        );
+      }
+      if (notes.length === 0) return { tools, invalid, onBranchOnly };
+      return { tools, invalid, onBranchOnly, note: notes.join(' ') };
     }),
   );
 }

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

@@ -1,4 +1,3 @@
-import express from 'express';
 import { describe, expect, it } from 'vitest';
 import {
   CALL_TOOL_CHAIN_NAME,
@@ -9,21 +8,9 @@ import {
   splitCallLine,
 } from '@bevel-software/platform-mcp-core';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/tool-manuals.contract.js';
-import { ToolRegistry } from '../tool-registry.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/index.js';
 import type { UtcpTool } from '../tool.contract.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
-import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
-import { RipgrepPatternMatcher } from '../../workspace/index.js';
-import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
-import { registerPluginsTools } from '../../plugins/plugins.tools.js';
-import { registerSkillsTools } from '../../skills/skills.tools.js';
-import { registerToolManualsTools } from '../../tool-manuals/tool-manuals.tools.js';
-import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { UuidSessionSink } from '../../workspace/session-sink.js';
-import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
+import type { registerSkillsTools } from '../../skills/index.js';
 import { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength, firstSentenceEnd } from '../description-length.js';
 import { CAN_WRITE_CLAUSE } from '../../tool-helpers/index.js';
 import {
@@ -31,9 +18,8 @@ import {
   sharedFileRules,
 } from '../../agent-instructions/index.js';
 import { isPlatformFile, platformFilesByDepth } from '@bevel-software/platform-shared';
-import { GET_AGENT_GUIDE_TOOL, GUIDE_FIRST_SENTENCE, guideFirstDescription } from '../guide-first.js';
-import { registerAgentGuideTool } from '../../agent-guide/agent-guide.tools.js';
-import { agentGuideSections } from '../../agent-guide/agent-guide.js';
+import { GET_AGENT_GUIDE_TOOL, GUIDE_FIRST_SENTENCE } from '../guide-first.js';
+import { emptySkills, hexisTools, servedMetaTools, unused } from '../../../__tests__/hexis-catalog.js';
 
 /**
  * The cap exists because clients cut a long tool description, and they cut it
@@ -43,104 +29,11 @@ import { agentGuideSections } from '../../agent-guide/agent-guide.js';
  * NAMING the tool: the next paragraph someone appends to a description has to
  * answer to this test rather than to an agent's truncated catalog.
  *
- * Every registrar Hexis owns is mounted here, on stand-ins, because the
- * descriptions are the only thing under test: a stand-in that is never called
- * is honest about that. Tools PROXIED from connected MCP servers are not
+ * The catalog is every registrar Hexis owns, mounted on stand-ins (see
+ * `hexis-catalog.ts`). Tools PROXIED from connected MCP servers are not
  * measured — their text is the other server's.
  */
 
-/** Dependencies the registrars take but never touch while they are only building defs. */
-const unused = <T,>(): T => ({}) as T;
-
-/** A `.tool` catalog with nothing in it: the shortest honest answer for a listing. */
-const emptyManuals = {
-  listLocalOnly: async () => [],
-  listAll: async () => [],
-  list: async () => [],
-  listInvalid: async () => [],
-} as unknown as Parameters<typeof registerToolManualsTools>[4];
-
-/** A skill catalog with nothing in it — the per-user skill line is then one fixed sentence. */
-const emptySkills = { listSkills: async () => [] } as unknown as Parameters<typeof registerSkillsTools>[4];
-
-/**
- * The meta-tools as the hosted endpoint builds them (`mcp.service.ts`):
- * examples written against the namespace it registers the knowledge-base tools
- * under and against the catalog it serves, and the chain without the rules it
- * states only in the shared places. So the chain description measured here
- * carries the worked call a client is really sent, which is its longest form.
- */
-function servedMetaTools(external: readonly UtcpTool[]) {
-  return codeModeMetaTools(
-    EXTERNAL_KB_MANUAL_NAME,
-    external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
-    { sharedRulesPointer: '' },
-    // As the hosted endpoint serves them: opening with the guide-first
-    // sentence, through the one helper the endpoint itself uses.
-  ).map((t) => ({ ...t, description: guideFirstDescription(t.description) }));
-}
-
-/** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
-async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = emptySkills): Promise<UtcpTool[]> {
-  const registry = new ToolRegistry();
-  const router = express.Router();
-  const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
-  const toolHandler = createToolHandlerFactory(unused());
-  const kb = testKbContext();
-  const gate = { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() };
-
-  registerWorkspaceTools(
-    registry,
-    router,
-    toolAuth,
-    toolHandler,
-    unused(),
-    unused(),
-    unused(),
-    kb,
-    gate,
-    new RoutineWritePolicyService(),
-    new UuidSessionSink(),
-    undefined,
-    undefined,
-    // The two upload tools are mounted only when a store is supplied, and
-    // every real composition supplies one: without it they would be the two
-    // descriptions this suite never measured.
-    unused(),
-    // The guide reader, not needed to build defs; then the download store,
-    // mounted on the same terms as the upload one.
-    undefined,
-    unused(),
-    // Starter packs and the tree walk, not needed; then the grep matcher,
-    // mounted on the same terms (it spawns no worker until a search runs).
-    undefined,
-    undefined,
-    new RipgrepPatternMatcher(),
-  );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
-  registerPluginsTools(registry, kb);
-  registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
-  registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
-    accessControl: unused(),
-    variableStatus: unused(),
-    kb,
-  });
-  // The guide's own tool, with the platform's sections: the one description
-  // that lists the sections is measured with the list it really carries.
-  registerAgentGuideTool(registry, router, toolAuth, toolHandler, () => agentGuideSections(kb.layout));
-
-  const byName = new Map<string, UtcpTool>();
-  // The meta-tools as a client is served them (`mcp.service.ts` opens each
-  // with the guide-first sentence at the mount), so the catalog measured here
-  // is the catalog that goes out rather than the bare constant.
-  const external = (await registry.listExternal()) as UtcpTool[];
-  const metaTools = servedMetaTools(external);
-  for (const tool of [...(await registry.listInternal()), ...external, ...metaTools]) {
-    byName.set(tool.name, tool as UtcpTool);
-  }
-  return [...byName.values()];
-}
-
 describe('no Hexis tool description is long enough to be cut', () => {
   it(`keeps every description a client is handed within ${TOOL_DESCRIPTION_CAP} characters`, async () => {
     const over = (await hexisTools())