@bevel-software/platform-core-backend 0.4.0 → 0.5.0

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

@@ -84,6 +84,10 @@ export function createToolManualsAgentRoutes(
  * Browser-facing tool-manual routes (mounted under the JWT auth middleware):
  *   GET  /tools           — the caller's accessible `.tool` manuals (summaries).
  *   POST /tools/preview    — validate a draft `.tool` for the renderer.
+ *   GET  /tools/:slug      — one readable manual with description + capabilities
+ *                            (the tool page). Registered LAST so no future
+ *                            literal sibling is shadowed by the param segment;
+ *                            `preview` is POST-only, so it never collides.
  */
 export function createToolManualsBrowserRoutes(toolManualService: IToolManualService): express.Router {
   const router = express.Router();
@@ -106,5 +110,22 @@ export function createToolManualsBrowserRoutes(toolManualService: IToolManualSer
     res.json(await toolManualService.preview(content));
   });
 
+  router.get('/tools/:slug', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      // `getDetail` returns null for BOTH "no such slug" and "you can't read it",
+      // and this route keeps them indistinguishable: a distinct 403 would confirm
+      // the existence of a tool the caller isn't allowed to know about. Same
+      // fail-closed posture as the agent-facing `/tools/:slug/manual`.
+      const tool = await toolManualService.getDetail(email, String(req.params.slug));
+      if (!tool) return void res.status(404).json({ error: 'Not found' });
+      res.json({ tool });
+    } catch (err) {
+      console.error('[tool-manuals] detail failed:', err);
+      res.status(500).json({ error: 'Failed to load tool' });
+    }
+  });
+
   return router;
 }

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

@@ -9,7 +9,7 @@ import {
   DefaultVariableSubstitutor,
   type CallTemplate,
 } from '@utcp/sdk';
-import { DEFAULT_BRANCH, TOOLS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, GROUPS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../workspace/workspace.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
@@ -28,6 +28,8 @@ import {
   type IToolManualService,
   type ToolManualDescriptor,
   type ToolManualSummary,
+  type ToolManualDetail,
+  type ToolCapability,
   type UtcpManualDict,
   type ToolManualPreview,
   type ToolManualType,
@@ -38,6 +40,13 @@ import {
 
 const CACHE_TTL_MS = 60_000;
 
+/**
+ * How many embedded tools a manual may advertise on the tool page. A `.tool` is
+ * author-written, so its `tools` array is unbounded input; the page renders one
+ * bullet per entry, and a thousand of them is a broken page, not a useful one.
+ */
+const MAX_CAPABILITIES = 100;
+
 /**
  * UTCP namespaces a user `.tool` may NOT claim: they belong to built-in manuals
  * whose loopback creds are pre-seeded on the agent's code-mode client (the
@@ -154,16 +163,25 @@ export class ToolManualService implements IToolManualService {
   }
 
   async listAccessible(userEmail: string): Promise<ToolManualSummary[]> {
-    const manuals = await this.accessibleManuals(userEmail);
-    return manuals.map((m) => ({
-      slug: m.slug,
-      name: m.name,
-      path: m.path,
-      type: m.type,
-      variables: m.variables,
-      remote: m.remote,
-      setup: m.setup,
-    }));
+    return (await this.accessibleManuals(userEmail)).map(toSummary);
+  }
+
+  async listAllSummaries(): Promise<ToolManualSummary[]> {
+    return (await this.scan()).map(toSummary);
+  }
+
+  async getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null> {
+    // Resolved through `accessibleManuals` rather than `scan()` + a canRead call
+    // so the cache, the dedupe, the mcp-oauth decoration and the fail-closed
+    // batch ACL all apply exactly as they do to the catalog listing — one read
+    // 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;
+    return {
+      ...toSummary(found),
+      description: found.description ?? null,
+      capabilities: capabilitiesOf(found),
+    };
   }
 
   async listLocalOnly(userEmail: string): Promise<{ name: string; path: string }[]> {
@@ -252,7 +270,7 @@ export class ToolManualService implements IToolManualService {
   async preview(content: string): Promise<ToolManualPreview> {
     let descriptor: ToolManualDescriptor;
     try {
-      descriptor = normalizeToolManual('draft', 'Tools/draft.tool', content);
+      descriptor = normalizeToolManual('draft', 'Groups/draft.tool', content);
     } catch (err) {
       return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
     }
@@ -467,12 +485,14 @@ export class ToolManualService implements IToolManualService {
     } catch {
       return [];
     }
-    const root = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName, TOOLS_DIR);
+    const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
-    const files = (await walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))).map((rel) => ({
-      abs: path.join(root, rel),
-      rel: `${TOOLS_DIR}/${rel}`,
-    }));
+    // A `.tool` sits under `Groups/`, beside the skills that use it.
+    const files: { abs: string; rel: string }[] = [];
+    const root = path.join(kbRoot, GROUPS_DIR);
+    for (const rel of await walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))) {
+      files.push({ abs: path.join(root, rel), rel: `${GROUPS_DIR}/${rel}` });
+    }
 
     const parsed: ToolManualDescriptor[] = [];
     for (const f of files) {
@@ -510,6 +530,47 @@ export class ToolManualService implements IToolManualService {
 
 // --- helpers ------------------------------------------------------------------
 
+/**
+ * The one descriptor → summary projection, shared by every list surface
+ * (`listAccessible`, `listAllSummaries`, and the summary half of `getDetail`).
+ */
+function toSummary(m: ToolManualDescriptor): ToolManualSummary {
+  return {
+    slug: m.slug,
+    name: m.name,
+    path: m.path,
+    type: m.type,
+    description: m.description,
+    variables: m.variables,
+    remote: m.remote,
+    setup: m.setup,
+  };
+}
+
+/**
+ * What an `inline` manual's embedded tools say the assistant can do. `tools` is
+ * typed `unknown[]` (it is only validated when actually served as a UTCP
+ * manual), so every entry is re-checked here: an entry without a string `name`
+ * has nothing to display and is dropped rather than rendering a blank bullet.
+ * Non-inline manuals discover their tools over the network at call time, so
+ * there is nothing to derive without a round-trip this endpoint won't make.
+ */
+function capabilitiesOf(m: ToolManualDescriptor): ToolCapability[] {
+  if (m.type !== 'inline' || !Array.isArray(m.tools)) return [];
+  const out: ToolCapability[] = [];
+  for (const entry of m.tools) {
+    if (out.length >= MAX_CAPABILITIES) break;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const t = entry as Record<string, unknown>;
+    if (typeof t.name !== 'string' || !t.name.trim()) continue;
+    out.push({
+      name: t.name.trim(),
+      description: typeof t.description === 'string' && t.description.trim() ? t.description.trim() : null,
+    });
+  }
+  return out;
+}
+
 function baseName(rel: string): string {
   const base = rel.slice(rel.lastIndexOf('/') + 1);
   return base.replace(/\.tool$/i, '');
@@ -600,6 +661,14 @@ export function normalizeToolManual(
     type,
   };
 
+  // Cosmetic prose for the browser tool page. Unlike every other field here, a
+  // malformed value is IGNORED rather than thrown on: `description` buys the
+  // reader a sentence, and no sentence is worth taking a working integration out
+  // of the catalog (a throw skips the whole file). So: a non-empty string wins,
+  // anything else — number, object, null, blank — silently leaves it absent.
+  const description = typeof obj.description === 'string' ? obj.description.trim() : '';
+  if (description) descriptor.description = description;
+
   const variables = normalizeVariables(obj.variables);
   if (variables.length) descriptor.variables = variables;
 

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

@@ -1,202 +1,206 @@
-import type { Router, RequestHandler } from 'express';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { workspaceIdForBranch } from '../workspace/workspace.service.js';
-import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
-import type { IToolManualService } from './tool-manuals.contract.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.
- */
-export interface VariableStatusPort {
-  statusFor(
-    userId: string,
-    keys: string[],
-  ): Promise<{ key: string; adminConfigured: boolean; userConfigured: boolean; userAuthorized?: boolean }[]>;
-}
-
-/**
- * Registers the tool-manual catalog tools (both surfaces) and hosts their
- * endpoints:
- *
- *  - `list_local_tools` — local-only manuals (`remote: false`) the remote proxy
- *    can't serve; the agent reads their `.tool` path and self-configures.
- *  - `list_tool_setup` — configuration status of every accessible manual, so an
- *    agent can EXPLAIN the remaining setup to the admin. Deliberately
- *    read-only: secret VALUES are never set (or returned) through a tool — the
- *    admin pastes them into the tool editor; users sign in on /connect.
- */
-export function registerToolManualsTools(
-  registry: IToolRegistry,
-  router: Router,
-  toolAuth: RequestHandler,
-  toolHandler: ToolHandlerFactory,
-  toolManualService: IToolManualService,
-  deps: {
-    accessControl: IAccessControl;
-    variableStatus: VariableStatusPort;
-  },
-): void {
-  registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
-  registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
-
-  router.post(
-    '/agent/tools/list_local_tools',
-    toolAuth,
-    toolHandler(async (_args, ctx: ToolContext) => ({
-      tools: await toolManualService.listLocalOnly(ctx.user.email),
-    })),
-  );
-
-  const defaultWs = workspaceIdForBranch(DEFAULT_BRANCH);
-  const varKey = (manualName: string, varName: string) => utcpNamespacedKey(manualName, varName);
-
-  const listSetupDef = toolDef({
-    name: 'list_tool_setup',
-    description:
-      'Configuration status of every `.tool` the current user can access: what each tool needs set up and ' +
-      'what is already configured. Results are scoped to the caller — a `.tool` the caller cannot READ is ' +
-      'absent entirely, and all status flags reflect the caller\'s own state. Per tool: `setup` describes ' +
-      'an MCP server\'s sign-in requirement (`open` = none; `oauth-auto` = sign-in was configured ' +
-      'automatically; `oauth-manual` = the provider does not support automatic registration, so a writer ' +
-      'must declare the OAuth provider in the `.tool` file and paste its client secret into the tool ' +
-      'editor). Per variable: whether the shared (admin) value is set, whether the CURRENT user has ' +
-      'set/authorized their own, and whether it is an OAuth sign-in (users authorize those on the /connect ' +
-      'page, never by typing a value). `canWrite` = the caller may write THAT `.tool` FILE (per-file access ' +
-      'from its frontmatter `write:`/`owner:` verbs and the access.md chain — NOT a platform role), which ' +
-      'is exactly what gates setting its shared secrets: the people who manage the file configure the tool. ' +
-      '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.',
-    path: '/api/agent/tools/list_tool_setup',
-    inputs: { type: 'object', properties: {}, required: [], additionalProperties: false },
-    outputs: {
-      type: 'object',
-      properties: {
-        tools: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              slug: { type: 'string' },
-              name: { type: 'string', description: 'The manual id — the namespace secrets bind to.' },
-              path: { type: 'string' },
-              type: { type: 'string' },
-              setup: {
-                type: ['object', 'null'],
-                description: 'MCP auto-discovery setup requirement; null for non-mcp tools.',
-                properties: { kind: { type: 'string' }, reason: { type: 'string' } },
-              },
-              canWrite: { type: 'boolean' },
-              variables: {
-                type: 'array',
-                items: {
-                  type: 'object',
-                  properties: {
-                    name: { type: 'string' },
-                    scope: { type: 'string', description: '`admin` (one shared value) or `user` (per user).' },
-                    label: { type: ['string', 'null'] },
-                    oauth: { type: 'boolean', description: 'Filled by signing in on /connect, not by a value.' },
-                    adminConfigured: {
-                      type: 'boolean',
-                      description:
-                        'Shared value set (plain admin vars), or the owner finished provider setup (OAuth vars).',
-                    },
-                    userConfigured: { type: 'boolean' },
-                    authorized: { type: ['boolean', 'null'], description: 'OAuth vars: current user signed in.' },
-                  },
-                  required: ['name', 'scope', 'oauth', 'adminConfigured', 'userConfigured'],
-                },
-              },
-            },
-            required: ['slug', 'name', 'path', 'type', 'canWrite', 'variables'],
-          },
-        },
-      },
-      required: ['tools'],
-    },
-    tags: ['tools'],
-  });
-  registry.registerInternalTool(listSetupDef);
-  registry.registerExternalTool(listSetupDef);
-  router.post(
-    '/agent/tools/list_tool_setup',
-    toolAuth,
-    toolHandler(async (_args, ctx: ToolContext) => {
-      const manuals = await toolManualService.listAccessible(ctx.user.email);
-      const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
-      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,
-            };
-          }),
-        })),
-      );
-      return { tools };
-    }),
-  );
-}
-
-/** "Local-only tools configured for you: `a`, `b`." (or a none note), filtered to what the caller may read. */
-async function localToolsLine(svc: IToolManualService, userEmail?: string): Promise<string> {
-  if (!userEmail) return 'No local-only tools are currently configured.';
-  const tools = await svc.listLocalOnly(userEmail);
-  if (tools.length === 0) return 'No local-only tools are currently configured.';
-  return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
-}
-
-async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
-  return toolDef({
-    name: 'list_local_tools',
-    description:
-      'List tools your workspace admins configured that run ONLY in a local environment ' +
-      '(e.g. a self-hosted MCP server on localhost) and therefore cannot be called through this ' +
-      'remote endpoint. Each entry gives the tool’s name and its `.tool` file path in the knowledge ' +
-      'base — read that file with `read_file` and configure the tool yourself in your local setup ' +
-      '(e.g. add the MCP server to your client). ' +
-      (await localToolsLine(svc, userEmail)),
-    path: '/api/agent/tools/list_local_tools',
-    inputs: { type: 'object', properties: {}, additionalProperties: false },
-    outputs: {
-      type: 'object',
-      properties: {
-        tools: {
-          type: 'array',
-          description: 'Local-only tools (name + KB path).',
-          items: {
-            type: 'object',
-            properties: {
-              name: { type: 'string' },
-              path: { type: 'string', description: 'KB path of the `.tool` file (read it with read_file).' },
-            },
-          },
-        },
-      },
-    },
-    tags: ['tools'],
-  });
-}
+import type { Router, RequestHandler } from 'express';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
+import type { IToolManualService } from './tool-manuals.contract.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.
+ */
+export interface VariableStatusPort {
+  statusFor(
+    userId: string,
+    keys: string[],
+  ): Promise<{ key: string; adminConfigured: boolean; userConfigured: boolean; userAuthorized?: boolean }[]>;
+}
+
+/**
+ * Registers the tool-manual catalog tools (both surfaces) and hosts their
+ * endpoints:
+ *
+ *  - `list_local_tools` — local-only manuals (`remote: false`) the remote proxy
+ *    can't serve; the agent reads their `.tool` path and self-configures.
+ *  - `list_tool_setup` — configuration status of every accessible manual, so an
+ *    agent can EXPLAIN the remaining setup to the admin. Deliberately
+ *    read-only: secret VALUES are never set (or returned) through a tool — the
+ *    admin pastes them into the tool editor; users sign in on /connect.
+ */
+export function registerToolManualsTools(
+  registry: IToolRegistry,
+  router: Router,
+  toolAuth: RequestHandler,
+  toolHandler: ToolHandlerFactory,
+  toolManualService: IToolManualService,
+  deps: {
+    accessControl: IAccessControl;
+    variableStatus: VariableStatusPort;
+  },
+): void {
+  registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+  registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+
+  router.post(
+    '/agent/tools/list_local_tools',
+    toolAuth,
+    toolHandler(async (_args, ctx: ToolContext) => ({
+      tools: await toolManualService.listLocalOnly(ctx.user.email),
+    })),
+  );
+
+  // A FUNCTION, not a constant — this factory runs at boot, and on a
+  // setup-screen deployment the branch model is applied AFTER boot. Only a
+  // read inside a handler body sees the configured `DEFAULT_BRANCH`; a
+  // construction-time capture would hold the empty pre-setup id until restart.
+  const defaultWs = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  const varKey = (manualName: string, varName: string) => utcpNamespacedKey(manualName, varName);
+
+  const listSetupDef = toolDef({
+    name: 'list_tool_setup',
+    description:
+      'Configuration status of every `.tool` the current user can access: what each tool needs set up and ' +
+      'what is already configured. Results are scoped to the caller — a `.tool` the caller cannot READ is ' +
+      'absent entirely, and all status flags reflect the caller\'s own state. Per tool: `setup` describes ' +
+      'an MCP server\'s sign-in requirement (`open` = none; `oauth-auto` = sign-in was configured ' +
+      'automatically; `oauth-manual` = the provider does not support automatic registration, so a writer ' +
+      'must declare the OAuth provider in the `.tool` file and paste its client secret into the tool ' +
+      'editor). Per variable: whether the shared (admin) value is set, whether the CURRENT user has ' +
+      'set/authorized their own, and whether it is an OAuth sign-in (users authorize those on the /connect ' +
+      'page, never by typing a value). `canWrite` = the caller may write THAT `.tool` FILE (per-file access ' +
+      'from its frontmatter `write:`/`owner:` verbs and the access.md chain — NOT a platform role), which ' +
+      'is exactly what gates setting its shared secrets: the people who manage the file configure the tool. ' +
+      '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.',
+    path: '/api/agent/tools/list_tool_setup',
+    inputs: { type: 'object', properties: {}, required: [], additionalProperties: false },
+    outputs: {
+      type: 'object',
+      properties: {
+        tools: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              slug: { type: 'string' },
+              name: { type: 'string', description: 'The manual id — the namespace secrets bind to.' },
+              path: { type: 'string' },
+              type: { type: 'string' },
+              setup: {
+                type: ['object', 'null'],
+                description: 'MCP auto-discovery setup requirement; null for non-mcp tools.',
+                properties: { kind: { type: 'string' }, reason: { type: 'string' } },
+              },
+              canWrite: { type: 'boolean' },
+              variables: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name: { type: 'string' },
+                    scope: { type: 'string', description: '`admin` (one shared value) or `user` (per user).' },
+                    label: { type: ['string', 'null'] },
+                    oauth: { type: 'boolean', description: 'Filled by signing in on /connect, not by a value.' },
+                    adminConfigured: {
+                      type: 'boolean',
+                      description:
+                        'Shared value set (plain admin vars), or the owner finished provider setup (OAuth vars).',
+                    },
+                    userConfigured: { type: 'boolean' },
+                    authorized: { type: ['boolean', 'null'], description: 'OAuth vars: current user signed in.' },
+                  },
+                  required: ['name', 'scope', 'oauth', 'adminConfigured', 'userConfigured'],
+                },
+              },
+            },
+            required: ['slug', 'name', 'path', 'type', 'canWrite', 'variables'],
+          },
+        },
+      },
+      required: ['tools'],
+    },
+    tags: ['tools'],
+  });
+  registry.registerInternalTool(listSetupDef);
+  registry.registerExternalTool(listSetupDef);
+  router.post(
+    '/agent/tools/list_tool_setup',
+    toolAuth,
+    toolHandler(async (_args, ctx: ToolContext) => {
+      const manuals = await toolManualService.listAccessible(ctx.user.email);
+      const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
+      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,
+            };
+          }),
+        })),
+      );
+      return { tools };
+    }),
+  );
+}
+
+/** "Local-only tools configured for you: `a`, `b`." (or a none note), filtered to what the caller may read. */
+async function localToolsLine(svc: IToolManualService, userEmail?: string): Promise<string> {
+  if (!userEmail) return 'No local-only tools are currently configured.';
+  const tools = await svc.listLocalOnly(userEmail);
+  if (tools.length === 0) return 'No local-only tools are currently configured.';
+  return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
+}
+
+async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
+  return toolDef({
+    name: 'list_local_tools',
+    description:
+      'List tools your workspace admins configured that run ONLY in a local environment ' +
+      '(e.g. a self-hosted MCP server on localhost) and therefore cannot be called through this ' +
+      'remote endpoint. Each entry gives the tool’s name and its `.tool` file path in the knowledge ' +
+      'base — read that file with `read_file` and configure the tool yourself in your local setup ' +
+      '(e.g. add the MCP server to your client). ' +
+      (await localToolsLine(svc, userEmail)),
+    path: '/api/agent/tools/list_local_tools',
+    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    outputs: {
+      type: 'object',
+      properties: {
+        tools: {
+          type: 'array',
+          description: 'Local-only tools (name + KB path).',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              path: { type: 'string', description: 'KB path of the `.tool` file (read it with read_file).' },
+            },
+          },
+        },
+      },
+    },
+    tags: ['tools'],
+  });
+}