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

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

@@ -20,11 +20,11 @@ import {
 // auth type, so a `.tool` naming it validates here.
 import { findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey } from '@bevel-software/platform-mcp-core';
 import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
-import type { PluginSource } from '../plugins/discovery/plugin-source.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { PluginSource } from '../plugins/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import { redactSecret } from '../../shared/redact-secret.js';
 import { printable } from '../../shared/printable.js';
@@ -43,6 +43,7 @@ import {
   EXTERNAL_KB_MANUAL_NAME,
   MAX_CAPABILITIES,
   type IToolManualService,
+  type ConnectorScope,
   type ToolManualDescriptor,
   type ToolManualDescriptorBase,
   type ToolManualSummary,
@@ -304,8 +305,8 @@ export class ToolManualService implements IToolManualService {
     return (await this.accessibleManuals(userEmail)).map(toSummary);
   }
 
-  async listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog> {
-    const { manuals, invalid } = await this.accessibleScan(userEmail);
+  async listAccessibleCatalog(userEmail: string, within?: ConnectorScope): Promise<AccessibleCatalog> {
+    const { manuals, invalid } = await this.accessibleScan(userEmail, within);
     return { tools: manuals.map(toSummary), invalid };
   }
 
@@ -313,8 +314,8 @@ export class ToolManualService implements IToolManualService {
     return (await this.scan()).manuals.map(toSummary);
   }
 
-  async catalogFingerprints(userEmail: string): Promise<string[]> {
-    return (await this.accessibleManuals(userEmail)).map(manualFingerprint);
+  async catalogFingerprints(userEmail: string, within?: ConnectorScope): Promise<string[]> {
+    return (await this.accessibleManuals(userEmail, within)).map(manualFingerprint);
   }
 
   async getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null> {
@@ -341,14 +342,15 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
-  async listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]> {
-    const manuals = await this.accessibleManuals(userEmail);
+  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 }));
   }
 
   async listDeclaredOnlyOnBranch(
     userEmail: string,
     branch: string,
+    within?: ConnectorScope,
   ): Promise<{ name: string; path: string; type: ToolManualType }[]> {
     if (!branch || branch === this.kb.defaultBranch) return [];
     // Only a draft this process already holds a clone of — the one the caller
@@ -377,7 +379,7 @@ export class ToolManualService implements IToolManualService {
       pending.map((m) => m.path),
     );
     return pending
-      .filter((m) => allowed.get(m.path) === true)
+      .filter((m) => allowed.get(m.path) === true && (within === undefined || within(m.path)))
       .map((m) => ({ name: m.name, path: m.path, type: m.type }));
   }
 
@@ -456,8 +458,11 @@ export class ToolManualService implements IToolManualService {
     return { name: m.name, type: m.type, remote: m.remote, healthCheck: m.healthCheck, callTemplate };
   }
 
-  async toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean }): Promise<CallTemplate[]> {
-    const manuals = await this.accessibleManuals(userEmail);
+  async toManualCallTemplates(
+    userEmail: string,
+    opts?: { remoteOnly?: boolean; within?: ConnectorScope },
+  ): Promise<CallTemplate[]> {
+    const manuals = await this.accessibleManuals(userEmail, opts?.within);
     const out: CallTemplate[] = [];
     for (const m of manuals) {
       // Remote consumers (the hosted MCP proxy) don't get local-only manuals —
@@ -474,11 +479,17 @@ export class ToolManualService implements IToolManualService {
     return out;
   }
 
-  async resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null> {
+  async resolveInlineManual(
+    userEmail: string,
+    slug: string,
+    opts?: { within?: ConnectorScope },
+  ): Promise<UtcpManualDict | null> {
     const found = (await this.scan()).manuals.find((m) => m.slug === slug);
     if (!found || found.type !== 'inline') return null;
     const wsId = this.kb.defaultWorkspaceId();
     if (!(await this.accessControl.canRead(wsId, userEmail, found.path))) return null;
+    // After the read gate, as every narrowing is: a connection's scope can only take away.
+    if (opts?.within && !opts.within(found.path)) return null;
     try {
       return manualSerializer.validateDict({
         utcp_version: '1.1.0',
@@ -590,8 +601,8 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
-  private async accessibleManuals(userEmail: string): Promise<ToolManualDescriptor[]> {
-    return (await this.accessibleScan(userEmail)).manuals;
+  private async accessibleManuals(userEmail: string, within?: ConnectorScope): Promise<ToolManualDescriptor[]> {
+    return (await this.accessibleScan(userEmail, within)).manuals;
   }
 
   /**
@@ -599,8 +610,12 @@ export class ToolManualService implements IToolManualService {
    * ONE `canReadBatch`. Both halves are paths in the same workspace judged by
    * the same rule, and splitting them into two calls would pay a second
    * round-trip to ask the same question.
+   *
+   * `within` narrows the answer to a connection's connectors, AFTER the read
+   * gate: it can take a manual out of what the caller may read, never put one
+   * in. Absent, the answer is the caller's whole readable catalog.
    */
-  private async accessibleScan(userEmail: string): Promise<ScanResult> {
+  private async accessibleScan(userEmail: string, within?: ConnectorScope): Promise<ScanResult> {
     const { manuals, invalid } = await this.scan();
     if (manuals.length === 0 && invalid.length === 0) return emptyScan();
     const wsId = this.kb.defaultWorkspaceId();
@@ -612,9 +627,10 @@ export class ToolManualService implements IToolManualService {
     // A REFUSED file is gated the same way a listed one is: its path is a fact
     // about the knowledge base, and "there is a broken tool at this path" is
     // not something to tell someone who may not read that path.
+    const inScope = (p: string) => allowed.get(p) === true && (within === undefined || within(p));
     return {
-      manuals: manuals.filter((m) => allowed.get(m.path) === true),
-      invalid: invalid.filter((i) => allowed.get(i.path) === true),
+      manuals: manuals.filter((m) => inScope(m.path)),
+      invalid: invalid.filter((i) => inScope(i.path)),
     };
   }
 

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

@@ -1,13 +1,11 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import { declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { ToolContext, ToolHandlerFactory } from '../tool-helpers/index.js';
+import { toolDef, declareRouteTool } from '../tool-helpers/index.js';
+import type { IAccessControl } from '../access/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
-import type { IToolManualService } from './tool-manuals.contract.js';
+import type { ConnectorScope, IToolManualService } from './tool-manuals.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 
 /**
@@ -53,7 +51,9 @@ export function registerToolManualsTools(
     hiddenTools?: HiddenToolSource;
   },
 ): void {
-  registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+  registry.registerExternalTool((ctx) =>
+    buildListLocalToolsDef(toolManualService, ctx.userEmail, ctx.connectionScope?.connectorFilter()),
+  );
   registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
   // The def above is built per catalog listing (its description names the
   // tools configured for THIS caller), so declare the arguments here as well:
@@ -61,12 +61,22 @@ export function registerToolManualsTools(
   // against them too.
   declareRouteTool('list_local_tools', LIST_LOCAL_TOOLS_INPUTS);
 
+  // The local server's discovery read (`discovery`): it asks this route at
+  // startup for the connectors it must materialize, whatever tools the
+  // connection is offered — a connection made as an agent configuration that omits
+  // the tool is answered its connectors, not refused, or the local server
+  // could not start for that agent at all.
   router.post(
     '/agent/tools/list_local_tools',
     toolAuth,
-    toolHandler(async (_args, ctx: ToolContext) => ({
-      tools: await toolManualService.listLocalOnly(ctx.user.email),
-    })),
+    toolHandler(async (_args, ctx: ToolContext) => {
+      const within = ctx.connectionScope?.connectorFilter();
+      return {
+        tools: await (within
+          ? toolManualService.listLocalOnly(ctx.user.email, within)
+          : toolManualService.listLocalOnly(ctx.user.email)),
+      };
+    }, { discovery: true }),
   );
 
   // A FUNCTION, not a constant — this factory runs at boot, and on a
@@ -245,12 +255,17 @@ export function registerToolManualsTools(
     toolHandler(async (args, ctx: ToolContext) => {
       // The in-app agent is focused on its own draft; an external caller names it.
       const branch = typeof args.branch === 'string' && args.branch ? args.branch : ctx.focusedBranch;
+      const within = ctx.connectionScope?.connectorFilter();
       // The catalog comes back whole — what parsed AND what was refused — from
       // ONE scan, so the refused files cost no second walk of the workspace and
       // the two halves cannot disagree about which files made it.
       const [{ tools: manuals, invalid }, pending] = await Promise.all([
-        toolManualService.listAccessibleCatalog(ctx.user.email),
-        branch ? toolManualService.listDeclaredOnlyOnBranch(ctx.user.email, branch) : Promise.resolve([]),
+        // Only the connectors the caller's connection loads: setup is counted
+        // for the tools this connection can call, not every one the person can.
+        within
+          ? toolManualService.listAccessibleCatalog(ctx.user.email, within)
+          : toolManualService.listAccessibleCatalog(ctx.user.email),
+        branch ? toolManualService.listDeclaredOnlyOnBranch(ctx.user.email, branch, within) : Promise.resolve([]),
       ]);
       const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
       const status = await deps.variableStatus.statusFor(ctx.user.id, allKeys);
@@ -303,9 +318,9 @@ export function registerToolManualsTools(
 }
 
 /** "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> {
+async function localToolsLine(svc: IToolManualService, userEmail?: string, within?: ConnectorScope): Promise<string> {
   if (!userEmail) return 'No local-only tools are currently configured.';
-  const tools = await svc.listLocalOnly(userEmail);
+  const tools = await (within ? svc.listLocalOnly(userEmail, within) : 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(', ')}.`;
 }
@@ -313,7 +328,7 @@ async function localToolsLine(svc: IToolManualService, userEmail?: string): Prom
 /** `list_local_tools` takes nothing; a const so the route and the def share one declaration. */
 const LIST_LOCAL_TOOLS_INPUTS = { type: 'object' as const, properties: {}, additionalProperties: false };
 
-async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
+async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string, within?: ConnectorScope): Promise<UtcpTool> {
   return toolDef({
     name: 'list_local_tools',
     description:
@@ -326,7 +341,7 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
       'machine. Otherwise each entry gives the tool’s name and its `.tool` file ' +
       'path in the knowledge base — read that file with `read_file` and wire the tool into your local ' +
       'setup by hand. ' +
-      (await localToolsLine(svc, userEmail)),
+      (await localToolsLine(svc, userEmail, within)),
     path: '/api/agent/tools/list_local_tools',
     inputs: LIST_LOCAL_TOOLS_INPUTS,
     outputs: {