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

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

@@ -68,7 +68,7 @@ describe('ToolManualService', () => {
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'tools-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(join(tools, 'weather.tool'), INLINE_TOOL);
     await writeFile(join(tools, 'billing.tool'), HTTP_TOOL);
@@ -87,6 +87,16 @@ describe('ToolManualService', () => {
     expect(list.map((m) => m.name)).toEqual(['weather']);
   });
 
+  test('listAllSummaries returns every manual regardless of caller access', async () => {
+    // The group index counts a group's tools for people who cannot read them,
+    // so this surface must ignore the ACL that `listAccessible` applies.
+    const service = svc(denyBilling);
+    expect((await service.listAccessible('user@x.eu')).map((m) => m.name)).toEqual(['weather']);
+    const all = await service.listAllSummaries();
+    expect(all.map((m) => m.name).sort()).toEqual(['billing', 'weather']);
+    expect(all.map((m) => m.path).sort()).toEqual(['Groups/billing.tool', 'Groups/weather.tool']);
+  });
+
   test('builds an inline manual as an http sub-manual call-template', async () => {
     const templates = await svc().toManualCallTemplates('user@x.eu');
     const inline = templates.find((t) => t.name === 'weather')!;
@@ -113,7 +123,7 @@ describe('ToolManualService', () => {
 
   test('manual names are alphanumeric (no underscores) for variable namespacing', async () => {
     root = await mkdtemp(join(tmpdir(), 'tools2-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(join(tools, 'my_cool-tool.tool'), JSON.stringify({ type: 'http', url: 'https://x.example.com/m' }));
     const list = await svc().listAccessible('user@x.eu');
@@ -123,7 +133,7 @@ describe('ToolManualService', () => {
 
   test('refuses a `.tool` whose manual name collides (no silent suffix)', async () => {
     root = await mkdtemp(join(tmpdir(), 'tools3-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // Both names normalize to `stripe`. The scanner keeps the first (sorted path
     // order) and REFUSES the duplicate rather than renaming it `stripe2` — a
@@ -134,12 +144,12 @@ describe('ToolManualService', () => {
     await writeFile(join(tools, 'b.tool'), JSON.stringify({ name: 'stripe!', type: 'http', url: 'https://b.example.com/m' }));
     const list = await svc().listAccessible('user@x.eu');
     expect(list.map((m) => m.name)).toEqual(['stripe']);
-    expect(list[0].path).toBe('Tools/a.tool');
+    expect(list[0].path).toBe('Groups/a.tool');
   });
 
   test('parses `variables` scopes (default admin, explicit user/admin)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsv-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(
       join(tools, 'weather.tool'),
@@ -164,7 +174,7 @@ describe('ToolManualService', () => {
 
   test('skips a `.tool` with a malformed `variables` entry (never silently mis-scoped)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsvbad-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(
       join(tools, 'weather.tool'),
@@ -175,7 +185,7 @@ describe('ToolManualService', () => {
 
   test('scopeOfVariable: declared scope wins; undeclared/unknown default to admin', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsscope-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(
       join(tools, 'weather.tool'),
@@ -211,7 +221,7 @@ describe('ToolManualService', () => {
   });
   const writeOAuthTool = async (variable: unknown) => {
     root = await mkdtemp(join(tmpdir(), 'toolsoauth-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(
       join(tools, 'g.tool'),
@@ -258,7 +268,7 @@ describe('ToolManualService', () => {
 
   test('parses `remote`: default true, explicit false, rejects non-boolean', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsrem-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(join(tools, 'pub.tool'), JSON.stringify({ name: 'pub', type: 'http', url: 'https://x/m' }));
     await writeFile(join(tools, 'loc.tool'), JSON.stringify({ name: 'loc', type: 'mcp', url: 'https://x/m', remote: false }));
@@ -271,21 +281,21 @@ describe('ToolManualService', () => {
 
   test('remoteOnly excludes local-only manuals; listLocalOnly returns them', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsrem2-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(join(tools, 'pub.tool'), JSON.stringify({ name: 'pub', type: 'http', url: 'https://x/m' }));
     await writeFile(join(tools, 'loc.tool'), JSON.stringify({ name: 'loc', type: 'http', url: 'https://x/m', remote: false }));
     const s = svc();
     expect((await s.toManualCallTemplates('user@x.eu', { remoteOnly: true })).map((t) => t.name).sort()).toEqual(['pub']);
     expect((await s.toManualCallTemplates('user@x.eu')).map((t) => t.name).sort()).toEqual(['loc', 'pub']);
-    expect(await s.listLocalOnly('user@x.eu')).toEqual([{ name: 'loc', path: 'Tools/loc.tool' }]);
+    expect(await s.listLocalOnly('user@x.eu')).toEqual([{ name: 'loc', path: 'Groups/loc.tool' }]);
     // The local-only manual is still browsable/editable regardless of the remote flag.
     expect((await s.listAccessible('user@x.eu')).map((m) => m.name).sort()).toEqual(['loc', 'pub']);
   });
 
   test('refuses a `.tool` that reproduces a reserved built-in namespace', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsresv-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // A `.tool` named exactly like the internal manual, or with the KB namespace as
     // an explicit id, would resolve the loopback creds seeded under that namespace.
@@ -298,7 +308,7 @@ describe('ToolManualService', () => {
 
   test('refuses a remote `.tool` whose url is a private/loopback/metadata host (SSRF)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsssrf-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(join(tools, 'imds.tool'), JSON.stringify({ name: 'imds', type: 'http', url: 'http://169.254.169.254/latest/meta-data' }));
     await writeFile(join(tools, 'loop.tool'), JSON.stringify({ name: 'loop', type: 'mcp', url: 'http://127.0.0.1:9000/mcp' }));
@@ -312,7 +322,7 @@ describe('ToolManualService', () => {
 
   test('SSRF guard still applies when a private host is combined with a template token in the query', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsssrf3-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // A `${VAR}` in the QUERY doesn't make the authority templated — the host is
     // still the literal metadata endpoint, so the guard must reject it. Only a
@@ -325,7 +335,7 @@ describe('ToolManualService', () => {
 
   test('refuses any `.tool` that references a platform-seeded variable (API_URL / CONNECTION_KEY)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsresvvar-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // Both reference forms (`${VAR}` and `$VAR`), in any `.tool` type and any
     // field — url query, header, an inline tool's call template. All refused at
@@ -348,7 +358,7 @@ describe('ToolManualService', () => {
 
   test('refuses a `.tool` that references a NAMESPACED reserved variable (`<ns>_API_URL` / `<ns>_CONNECTION_KEY`)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsresvns-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // The substitutor resolves a manual's variables under its UTCP namespace, so
     // `${BEVEL_CONNECTION_KEY}` reaches the same seeded platform bearer the bare
@@ -376,7 +386,7 @@ describe('ToolManualService', () => {
 
   test('refuses a `.tool` that declares a variable named API_URL or CONNECTION_KEY', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsresvdecl-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(
       join(tools, 'decl.tool'),
@@ -392,7 +402,7 @@ describe('ToolManualService', () => {
 
   test('SSRF guard validates the literal host even when userinfo or port are templated', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsssrf4-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // A `${VAR}` in the USERINFO or PORT doesn't make the hostname dynamic — the
     // fetch still targets the literal metadata IP, so the guard must reject it.
@@ -417,7 +427,7 @@ describe('ToolManualService', () => {
 
   test('SSRF guard exempts a local-only (remote:false) `.tool` and a templated url', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsssrf2-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // remote:false is never fetched server-side; a `${VAR}` url resolves at call time.
     await writeFile(join(tools, 'local.tool'), JSON.stringify({ name: 'localmcp', type: 'mcp', url: 'http://localhost:3333/mcp', remote: false }));
@@ -437,7 +447,7 @@ describe('ToolManualService', () => {
 
   test('parses `.tool` frontmatter: id is the manual name/namespace', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsfm-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // The tool IS the frontmatter: id + config in the one `---` block.
     await writeFile(
@@ -451,7 +461,7 @@ describe('ToolManualService', () => {
 
   test('snake_case id resolves scope via the UTCP doubled key', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolssnake-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(
       join(tools, 't.tool'),
@@ -465,7 +475,7 @@ describe('ToolManualService', () => {
 
   test('rejects a non-snake_case explicit id (file skipped)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsbadid-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     await writeFile(join(tools, 'x.tool'), '---\nid: My-Tool\ntype: http\nurl: https://x/m\n---\n');
     expect(await svc().listAccessible('user@x.eu')).toHaveLength(0);
@@ -473,7 +483,7 @@ describe('ToolManualService', () => {
 
   test('config after the closing fence is ignored (the tool is the frontmatter)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsnotes-'));
-    const tools = join(root, wsId, KB_DIR, 'Tools');
+    const tools = join(root, wsId, KB_DIR, 'Groups');
     await mkdir(tools, { recursive: true });
     // `type`/`url` live in the fence; the JSON after it is free-form notes.
     await writeFile(
@@ -485,6 +495,34 @@ describe('ToolManualService', () => {
     expect(m.type).toBe('mcp');
   });
 
+  test('parses `description` onto the descriptor, trimmed', async () => {
+    root = await mkdtemp(join(tmpdir(), 'toolsdesc-'));
+    const tools = join(root, wsId, KB_DIR, 'Groups');
+    await mkdir(tools, { recursive: true });
+    await writeFile(
+      join(tools, 'gh.tool'),
+      '---\nid: gh\ntype: mcp\nurl: https://mcp.example.com\ndescription: "  Read and write issues.  "\n---\n',
+    );
+    const [m] = await svc().listAccessible('user@x.eu');
+    expect(m.description).toBe('Read and write issues.');
+  });
+
+  test('a malformed `description` is IGNORED — it never takes a working `.tool` offline', async () => {
+    // Every other field throws on a bad value, which skips the whole file. This
+    // one must not: `description` buys a reader one sentence, and no sentence is
+    // worth removing a working integration from the catalog.
+    root = await mkdtemp(join(tmpdir(), 'toolsdescbad-'));
+    const tools = join(root, wsId, KB_DIR, 'Groups');
+    await mkdir(tools, { recursive: true });
+    await writeFile(join(tools, 'num.tool'), JSON.stringify({ name: 'num', type: 'http', url: 'https://x/m', description: 42 }));
+    await writeFile(join(tools, 'obj.tool'), JSON.stringify({ name: 'obj', type: 'http', url: 'https://x/m', description: { a: 1 } }));
+    await writeFile(join(tools, 'nul.tool'), JSON.stringify({ name: 'nul', type: 'http', url: 'https://x/m', description: null }));
+    await writeFile(join(tools, 'blank.tool'), JSON.stringify({ name: 'blank', type: 'http', url: 'https://x/m', description: '   ' }));
+    const byName = new Map((await svc().listAccessible('user@x.eu')).map((m) => [m.name, m]));
+    expect([...byName.keys()].sort()).toEqual(['blank', 'nul', 'num', 'obj']); // all four still in the catalog
+    for (const m of byName.values()) expect(m.description).toBeUndefined();
+  });
+
   test('preview validates an inline draft and reports its tools', async () => {
     const preview = await svc().preview(INLINE_TOOL);
     expect(preview.ok).toBe(true);

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

@@ -1,156 +1,156 @@
-import type { Server as HttpServer } from 'node:http';
-import express from 'express';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
-import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
-import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import { registerToolManualsTools } from '../tool-manuals.tools.js';
-import type { IToolManualService } from '../tool-manuals.contract.js';
-
-/**
- * `list_tool_setup` MUST respect the same access controls as every other tool
- * surface, resolved for THE CALLER:
- *
- *  - the catalog is read-gated: a `.tool` the caller can't READ is absent
- *    (via `listAccessible(callerEmail)` — default-deny, per email);
- *  - `canWrite` is the PER-FILE verdict (`canWrite(email, path)`), not a role;
- *  - configuration status is the caller's own (`statusFor(callerUserId, …)`).
- *
- * Exercised over a real express app with the real tool auth + handler
- * machinery, as two different users, so a caller-mixup (leaking another user's
- * catalog or status) can't slip through the composition.
- */
-
-const ALICE = { id: 'user-alice', email: 'alice@x.com', name: 'Alice' };
-const BOB = { id: 'user-bob', email: 'bob@x.com', name: 'Bob' };
-
-// Alice reads both tools and may write weather; Bob reads only weather, writes nothing.
-const CATALOG = [
-  {
-    slug: 'weather',
-    name: 'weather',
-    path: 'Tools/weather.tool',
-    type: 'mcp' as const,
-    setup: { kind: 'oauth-manual' as const, reason: 'no dynamic client registration' },
-    variables: [{ name: 'SHARED_KEY', scope: 'admin' as const, label: null }],
-  },
-  {
-    slug: 'billing',
-    name: 'billing',
-    path: 'Tools/billing.tool',
-    type: 'http' as const,
-    variables: [{ name: 'ORG_KEY', scope: 'admin' as const, label: null }],
-  },
-];
-
-const toolManualService = {
-  listAccessible: vi.fn(async (email: string) =>
-    email === ALICE.email ? CATALOG : CATALOG.filter((m) => m.slug === 'weather'),
-  ),
-  listLocalOnly: async () => [],
-} as unknown as IToolManualService;
-
-const accessControl = {
-  canWrite: vi.fn(
-    async (_ws: string, email: string, path: string) => email === ALICE.email && path === 'Tools/weather.tool',
-  ),
-} as never;
-
-const statusFor = vi.fn(async (userId: string, keys: string[]) =>
-  keys.map((key) => ({
-    key,
-    // Only Alice has configured anything — Bob's view must not inherit it.
-    adminConfigured: true,
-    userConfigured: userId === ALICE.id,
-  })),
-);
-
-let httpServer: HttpServer | undefined;
-
-const externalApiKeyService = {
-  looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
-  verifyAndLoadToken: async (t: string) =>
-    t === 'bevel_alice' ? { user: ALICE, tokenId: 'tok-a' } : t === 'bevel_bob' ? { user: BOB, tokenId: 'tok-b' } : null,
-} as never;
-
-async function start(): Promise<string> {
-  const registry = new ToolRegistry();
-  const internalToken = new InternalTokenService({ secret: 'test-secret' });
-  const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
-  const resolve = createToolContextResolver({
-    authService: {
-      getUserById: async (id: string) => (id === ALICE.id ? ALICE : id === BOB.id ? BOB : null),
-    } as never,
-    workspaceService: { getWorkspacePath: async () => '/tmp/ws' } as never,
-    workflowService: {} as never,
-    events: {} as never,
-    kbDirName: 'knowledge-base',
-    creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
-  });
-  const toolHandler = createToolHandlerFactory(resolve);
-
-  const app = express();
-  app.use(express.json());
-  const router = express.Router();
-  registerToolManualsTools(registry, router, toolAuth, toolHandler, toolManualService, {
-    accessControl,
-    variableStatus: { statusFor },
-  });
-  app.use('/api', router);
-
-  httpServer = await new Promise<HttpServer>((r) => {
-    const s = app.listen(0, () => r(s));
-  });
-  const port = (httpServer.address() as { port: number }).port;
-  return `http://127.0.0.1:${port}`;
-}
-
-afterEach(async () => {
-  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
-  httpServer = undefined;
-  vi.clearAllMocks();
-});
-
-const callSetup = (base: string, bearer: string) =>
-  fetch(`${base}/api/agent/tools/list_tool_setup`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', authorization: `Bearer ${bearer}` },
-    body: JSON.stringify({}),
-  });
-
-describe('list_tool_setup — access controls resolved for the caller', () => {
-  it('shows each caller only the tools THEY can read, with THEIR per-file canWrite', async () => {
-    const base = await start();
-
-    const aliceRes = await callSetup(base, 'bevel_alice');
-    expect(aliceRes.status).toBe(200);
-    const alice = (await aliceRes.json()) as { tools: { slug: string; canWrite: boolean }[] };
-    expect(alice.tools.map((t) => t.slug).sort()).toEqual(['billing', 'weather']);
-    expect(alice.tools.find((t) => t.slug === 'weather')!.canWrite).toBe(true);
-    expect(alice.tools.find((t) => t.slug === 'billing')!.canWrite).toBe(false);
-
-    const bobRes = await callSetup(base, 'bevel_bob');
-    expect(bobRes.status).toBe(200);
-    const bob = (await bobRes.json()) as {
-      tools: { slug: string; canWrite: boolean; variables: { userConfigured: boolean }[] }[];
-    };
-    // Bob can't read billing — it must be absent, not just canWrite=false.
-    expect(bob.tools.map((t) => t.slug)).toEqual(['weather']);
-    expect(bob.tools[0].canWrite).toBe(false);
-    // Status was resolved for BOB's user id, not leaked from Alice's.
-    expect(statusFor).toHaveBeenLastCalledWith(BOB.id, ['weather_SHARED_KEY']);
-    expect(bob.tools[0].variables[0].userConfigured).toBe(false);
-  });
-
-  it('rejects an unauthenticated call outright', async () => {
-    const base = await start();
-    const res = await fetch(`${base}/api/agent/tools/list_tool_setup`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({}),
-    });
-    expect(res.status).toBe(401);
-  });
-});
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import { registerToolManualsTools } from '../tool-manuals.tools.js';
+import type { IToolManualService } from '../tool-manuals.contract.js';
+
+/**
+ * `list_tool_setup` MUST respect the same access controls as every other tool
+ * surface, resolved for THE CALLER:
+ *
+ *  - the catalog is read-gated: a `.tool` the caller can't READ is absent
+ *    (via `listAccessible(callerEmail)` — default-deny, per email);
+ *  - `canWrite` is the PER-FILE verdict (`canWrite(email, path)`), not a role;
+ *  - configuration status is the caller's own (`statusFor(callerUserId, …)`).
+ *
+ * Exercised over a real express app with the real tool auth + handler
+ * machinery, as two different users, so a caller-mixup (leaking another user's
+ * catalog or status) can't slip through the composition.
+ */
+
+const ALICE = { id: 'user-alice', email: 'alice@x.com', name: 'Alice' };
+const BOB = { id: 'user-bob', email: 'bob@x.com', name: 'Bob' };
+
+// Alice reads both tools and may write weather; Bob reads only weather, writes nothing.
+const CATALOG = [
+  {
+    slug: 'weather',
+    name: 'weather',
+    path: 'Groups/weather.tool',
+    type: 'mcp' as const,
+    setup: { kind: 'oauth-manual' as const, reason: 'no dynamic client registration' },
+    variables: [{ name: 'SHARED_KEY', scope: 'admin' as const, label: null }],
+  },
+  {
+    slug: 'billing',
+    name: 'billing',
+    path: 'Groups/billing.tool',
+    type: 'http' as const,
+    variables: [{ name: 'ORG_KEY', scope: 'admin' as const, label: null }],
+  },
+];
+
+const toolManualService = {
+  listAccessible: vi.fn(async (email: string) =>
+    email === ALICE.email ? CATALOG : CATALOG.filter((m) => m.slug === 'weather'),
+  ),
+  listLocalOnly: async () => [],
+} as unknown as IToolManualService;
+
+const accessControl = {
+  canWrite: vi.fn(
+    async (_ws: string, email: string, path: string) => email === ALICE.email && path === 'Groups/weather.tool',
+  ),
+} as never;
+
+const statusFor = vi.fn(async (userId: string, keys: string[]) =>
+  keys.map((key) => ({
+    key,
+    // Only Alice has configured anything — Bob's view must not inherit it.
+    adminConfigured: true,
+    userConfigured: userId === ALICE.id,
+  })),
+);
+
+let httpServer: HttpServer | undefined;
+
+const externalApiKeyService = {
+  looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
+  verifyAndLoadToken: async (t: string) =>
+    t === 'bevel_alice' ? { user: ALICE, tokenId: 'tok-a' } : t === 'bevel_bob' ? { user: BOB, tokenId: 'tok-b' } : null,
+} as never;
+
+async function start(): Promise<string> {
+  const registry = new ToolRegistry();
+  const internalToken = new InternalTokenService({ secret: 'test-secret' });
+  const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
+  const resolve = createToolContextResolver({
+    authService: {
+      getUserById: async (id: string) => (id === ALICE.id ? ALICE : id === BOB.id ? BOB : null),
+    } as never,
+    workspaceService: { getWorkspacePath: async () => '/tmp/ws' } as never,
+    workflowService: {} as never,
+    events: {} as never,
+    kbDirName: 'knowledge-base',
+    creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
+  });
+  const toolHandler = createToolHandlerFactory(resolve);
+
+  const app = express();
+  app.use(express.json());
+  const router = express.Router();
+  registerToolManualsTools(registry, router, toolAuth, toolHandler, toolManualService, {
+    accessControl,
+    variableStatus: { statusFor },
+  });
+  app.use('/api', router);
+
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return `http://127.0.0.1:${port}`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.clearAllMocks();
+});
+
+const callSetup = (base: string, bearer: string) =>
+  fetch(`${base}/api/agent/tools/list_tool_setup`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${bearer}` },
+    body: JSON.stringify({}),
+  });
+
+describe('list_tool_setup — access controls resolved for the caller', () => {
+  it('shows each caller only the tools THEY can read, with THEIR per-file canWrite', async () => {
+    const base = await start();
+
+    const aliceRes = await callSetup(base, 'bevel_alice');
+    expect(aliceRes.status).toBe(200);
+    const alice = (await aliceRes.json()) as { tools: { slug: string; canWrite: boolean }[] };
+    expect(alice.tools.map((t) => t.slug).sort()).toEqual(['billing', 'weather']);
+    expect(alice.tools.find((t) => t.slug === 'weather')!.canWrite).toBe(true);
+    expect(alice.tools.find((t) => t.slug === 'billing')!.canWrite).toBe(false);
+
+    const bobRes = await callSetup(base, 'bevel_bob');
+    expect(bobRes.status).toBe(200);
+    const bob = (await bobRes.json()) as {
+      tools: { slug: string; canWrite: boolean; variables: { userConfigured: boolean }[] }[];
+    };
+    // Bob can't read billing — it must be absent, not just canWrite=false.
+    expect(bob.tools.map((t) => t.slug)).toEqual(['weather']);
+    expect(bob.tools[0].canWrite).toBe(false);
+    // Status was resolved for BOB's user id, not leaked from Alice's.
+    expect(statusFor).toHaveBeenLastCalledWith(BOB.id, ['weather_SHARED_KEY']);
+    expect(bob.tools[0].variables[0].userConfigured).toBe(false);
+  });
+
+  it('rejects an unauthenticated call outright', async () => {
+    const base = await start();
+    const res = await fetch(`${base}/api/agent/tools/list_tool_setup`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(401);
+  });
+});

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

@@ -8,5 +8,7 @@ export {
   EXTERNAL_KB_MANUAL_NAME,
   type IToolManualService,
   type ToolManualSummary,
+  type ToolManualDetail,
+  type ToolCapability,
   type ToolManualType,
 } from './tool-manuals.contract.js';

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

@@ -1,7 +1,7 @@
 import type { CallTemplate } from '@utcp/sdk';
 
 /**
- * Tool manuals — user-authored `*.tool` files under `Tools/` in the DEFAULT
+ * Tool manuals — user-authored `*.tool` files under `Groups/` in the DEFAULT
  * branch KB. Each is a UTCP *manual* (a pointer to where tools come from), not a
  * flattened tool list. Access-controlled exactly like Skills (default-deny ACL
  * on the `.tool` file path). The MCP/UTCP endpoint serves every manual a user
@@ -95,9 +95,16 @@ export interface ToolManualDescriptor {
    * catalog; namespacing doubles underscores in vault keys (`utcpNamespacedKey`).
    */
   name: string;
-  /** Repo-root-relative path of the `.tool` file (e.g. `Tools/weather.tool`). */
+  /** Repo-root-relative path of the `.tool` file (e.g. `Groups/Everyone/weather.tool`). */
   path: string;
   type: ToolManualType;
+  /**
+   * Optional one-line prose from the frontmatter, for humans browsing the
+   * catalog. PURELY COSMETIC — a malformed value is ignored rather than
+   * skipping the file (see `normalizeToolManual`), because a bad sentence must
+   * never take a working integration offline.
+   */
+  description?: string;
   /** For `http`/`mcp`: the endpoint URL (may contain `${VAR}` refs). */
   url?: string;
   httpMethod?: 'GET' | 'POST';
@@ -134,6 +141,8 @@ export interface ToolManualSummary {
   name: string;
   path: string;
   type: ToolManualType;
+  /** The frontmatter `description`, when the file declares a usable one. */
+  description?: string;
   /** Declared `${VAR}` scopes; empty when none declared. */
   variables?: ToolVariable[];
   /** `false` ⇒ local-only (not served to remote agents); absent/`true` ⇒ remote-capable. */
@@ -142,9 +151,48 @@ export interface ToolManualSummary {
   setup?: ToolManualSetup;
 }
 
+/** One thing an `inline` manual's embedded tool list says the assistant can do. */
+export interface ToolCapability {
+  name: string;
+  description: string | null;
+}
+
+/**
+ * A single tool manual for the BROWSER tool page (`GET /api/tools/:slug`): the
+ * summary plus the two human-facing fields the catalog listing has no use for.
+ * Both are normalized to `null` rather than left optional — the page renders a
+ * definite "nothing here" state, so an absent field and an empty one are the
+ * same thing to it.
+ */
+export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'> {
+  description: string | null;
+  /**
+   * What the tool actually exposes, derived from an `inline` manual's embedded
+   * `tools`. `http`/`mcp` manuals resolve their tools at call time (a network
+   * round-trip this endpoint deliberately does not make), so they report `[]`.
+   */
+  capabilities: ToolCapability[];
+}
+
 export interface IToolManualService {
   /** The `.tool` manuals the user can read, as summaries. */
   listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
+  /**
+   * One readable `.tool` by slug, with its description + capabilities, for the
+   * browser tool page. `null` when no such slug exists OR the caller can't read
+   * it — the two are deliberately indistinguishable (fail-closed: a 404 must not
+   * confirm that a tool the caller can't see exists).
+   */
+  getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
+
+  /**
+   * Every manual in the catalog, UNFILTERED by access — the mirror of
+   * `skillService.listSkills(undefined)`. For caller-INDEPENDENT counting only
+   * (the group index's "N tools", which a non-member is allowed to see as a
+   * number). Never surface a name, path or description from this to someone
+   * who cannot read the file; `listAccessible` is the surface for that.
+   */
+  listAllSummaries(): Promise<ToolManualSummary[]>;
   /**
    * Validated UTCP manual call-templates for the user's accessible `.tool`s —
    * one per file, ready for a UTCP client to `registerManual`. Each is validated