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

package/src/modules/tool-helpers/tool-handler.ts

@@ -13,8 +13,10 @@ import { branchHandlingFor, type BranchHandling } from './tool-def.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { ResolveToolContext } from './tool-context.js';
 import { argumentsRefusal } from './route-argument-check.js';
-import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/write-access.js';
-import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
+import { routeToolName, routeToolSchemasForRequest } from './route-tool-schemas.js';
+import { ConnectionScope, NOT_AVAILABLE_TO_CONNECTION } from '../agent-scope/index.js';
+import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/index.js';
+import '../tool-auth/index.js'; // Express Request.toolAuth augmentation
 
 function isAsyncIterable(v: unknown): v is AsyncIterable<unknown> {
   return (
@@ -40,6 +42,19 @@ export interface ToolHandlerOptions {
    * being refused).
    */
   branch?: BranchHandling;
+  /**
+   * The route is ALSO a discovery read of the connection's surface, which
+   * both MCP servers make whatever tools the connection is offered:
+   * `list_skills` and `get_skill` are how `prompts/list` and `prompts/get`
+   * are built, and `list_local_tools` is how the local server learns which
+   * connectors it must materialize. A connection's `platformTools` decides
+   * which tools its agent is OFFERED — the MCP listing and `tools/call`
+   * refuse the rest by name — not what its surface holds, so such a route is
+   * not refused for want of a `platformTools` entry. Its answer is still
+   * narrowed to the connection's skills or connectors by the handler, and a
+   * connection that loads nothing is refused it like any other route.
+   */
+  discovery?: boolean;
 }
 
 /**
@@ -255,6 +270,23 @@ export function createToolHandlerFactory(
             ? withoutBranch(args)
             : args;
         const ctx = await resolve(auth, abort.signal, sessionId);
+        // The connection's scope, before the tool runs, for every caller of a
+        // hosted platform tool — MCP, a chain, the local server, a script with
+        // a key. A connection made as an agent configuration that does not
+        // list this tool is refused it by name: the ONE policy,
+        // `ConnectionScope.platformToolRefusal`, which the platform-tool routes
+        // this handler does not host (the plugin-creation routes) ask as well.
+        const toolName = routeToolSchemasForRequest(req.originalUrl)?.name ?? routeToolName(req.originalUrl);
+        const scope =
+          ctx.connectionScope ?? (auth.agentPath ? ConnectionScope.gone(auth.agentPath) : ConnectionScope.everything());
+        // The handler narrows by the scope decided here, so a context built
+        // without one cannot read as Everything inside the tool either.
+        ctx.connectionScope = scope;
+        const refusal = scope.platformToolRefusal(toolName, { discovery: opts.discovery === true });
+        if (refusal) {
+          res.status(403).json(refusal);
+          return;
+        }
         if (resolved) ctx.branch = resolved.branch;
         let out = await handler(toolArgs, ctx);
         // A defaulted call's answer says which branch it ran on, so a caller
@@ -315,3 +347,5 @@ function withoutBranch(args: Record<string, unknown>): Record<string, unknown> {
 }
 
 export type ToolHandlerFactory = ReturnType<typeof createToolHandlerFactory>;
+
+export { NOT_AVAILABLE_TO_CONNECTION };

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

@@ -1,7 +1,8 @@
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { ConnectionScope } from '../agent-scope/index.js';
 import type { LocalFilesystem } from '@mastra/core/workspace';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WorkspaceService } from '../workspace/index.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';
 
 /**
@@ -58,6 +59,15 @@ export interface ToolContext {
    * tool that takes no branch.
    */
   branch?: string;
+  /**
+   * What the caller's connection may load (`modules/agent-scope`): resolved
+   * once per call from the agent configuration its credential connects as. The
+   * tool handler refuses a platform tool outside it before the tool runs; the
+   * tools that list skills and connectors narrow by it. Absent is Everything
+   * — and a context built without it for a credential that names an agent is
+   * refused every tool by the handler, never served Everything.
+   */
+  connectionScope?: ConnectionScope;
   abortSignal: AbortSignal;
   workspaceService: WorkspaceService;
   workflowService: IWorkflowService;

package/src/modules/tool-helpers/validate-token.ts

@@ -1,12 +1,13 @@
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import { InternalTokenService } from '../tool-auth/internal-token.service.js';
-import { createTokenVerifier } from '../tool-auth/tool-auth.middleware.js';
+import type { IExternalApiKeyService, InternalTokenService, ConnectionChoices } from '../tool-auth/index.js';
+import { createTokenVerifier } from '../tool-auth/index.js';
 import { createToolContextResolver, type ToolContextDeps } from './tool-context.js';
 import { ToolError, type ToolContext } from './tool.contract.js';
 
 export interface ToolValidatorDeps extends ToolContextDeps {
   externalApiKeyService: IExternalApiKeyService;
   internalTokenService: InternalTokenService;
+  /** Where an agent connection's current "Connect as" choice is read (see `createTokenVerifier`). */
+  connections?: ConnectionChoices;
 }
 
 /**
@@ -35,7 +36,7 @@ export type ValidateToken = (
 ) => Promise<ToolContext>;
 
 export function createToolValidator(deps: ToolValidatorDeps): ValidateToken {
-  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService, deps.authService);
+  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService, deps.authService, deps.connections);
   const resolve = createToolContextResolver(deps);
   return async (token, signal) => {
     let result;

package/src/modules/tool-manuals/__tests__/tool-manuals.archive.route.test.ts

@@ -12,6 +12,7 @@ import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { IToolManualService } from '../tool-manuals.contract.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { ConnectionScope, type IAgentScopeResolver } from '../../agent-scope/index.js';
 
 /**
  * `GET /agent/plugins/:folder/archive` — error taxonomy of the plugin-folder
@@ -27,10 +28,20 @@ let httpServer: HttpServer | undefined;
 let root: string;
 let wsDir: string;
 
-async function baseUrl(pluginIndex?: { catalog(): Promise<{ name: string; folders: string[] }[]> }): Promise<string> {
+async function baseUrl(
+  pluginIndex?: { catalog(): Promise<{ name: string; folders: string[] }[]> },
+  /** The connection's `.agent` choice; absent is Everything. */
+  connection?: {
+    agentPath: string;
+    agentScope?: Pick<IAgentScopeResolver, 'resolve'>;
+    /** Whether the person may read the plugin's files; default yes. */
+    readable?: boolean;
+  },
+  toolManualService: IToolManualService = {} as unknown as IToolManualService,
+): Promise<string> {
   const app = express();
   const manualAuth: express.RequestHandler = (req, _res, next) => {
-    req.toolAuth = { userId: 'u-1' } as never;
+    req.toolAuth = { userId: 'u-1', ...(connection ? { agentPath: connection.agentPath } : {}) } as never;
     next();
   };
   const workspaceService = {
@@ -39,16 +50,17 @@ async function baseUrl(pluginIndex?: { catalog(): Promise<{ name: string; folder
   } as unknown as WorkspaceService;
   const accessControl = {
     canReadBatch: vi.fn(async (_ws: string, _email: string, rels: string[]) => {
-      return new Map(rels.map((r) => [r, true]));
+      return new Map(rels.map((r) => [r, connection?.readable ?? true]));
     }),
   } as unknown as IAccessControl;
   app.use(
     '/api',
     createToolManualsAgentRoutes(
-      {} as unknown as IToolManualService,
+      toolManualService,
       manualAuth,
       async () => 'ali@example.com',
       { workspaceService, accessControl, kb: testKbContext({ kbDirName: KB }), disk: new NodeFs(), pluginIndex: pluginIndex as never },
+      connection?.agentScope,
     ),
   );
   httpServer = await new Promise<HttpServer>((resolve) => {
@@ -71,7 +83,53 @@ afterEach(async () => {
   await fs.rm(root, { recursive: true, force: true });
 });
 
+const OPS = { path: 'Agents/ops.agent', name: 'Ops' };
+/** A resolver that narrows every connection to `connectors`. */
+function loading(connectors: string[]): Pick<IAgentScopeResolver, 'resolve'> {
+  return { resolve: async () => ConnectionScope.narrowed(OPS, { skills: [], connectors, platformTools: null }, 'fp') };
+}
+
 describe('GET /agent/plugins/:folder/archive', () => {
+  it("a connection made as an .agent file archives only a plugin defining a connector the file loads", async () => {
+    const pluginDir = path.join(wsDir, KB, 'Plugins', 'GTM');
+    await fs.mkdir(pluginDir, { recursive: true });
+    await fs.writeFile(path.join(pluginDir, 'mcp.json'), '{"mcpServers":{}}', 'utf-8');
+    const archive = async (connectors: string[] | null) => {
+      const base = await baseUrl(undefined, {
+        agentPath: OPS.path,
+        ...(connectors ? { agentScope: loading(connectors) } : {}),
+      });
+      const res = await fetch(`${base}/api/agent/plugins/GTM/archive`);
+      await new Promise<void>((r) => httpServer!.close(() => r()));
+      httpServer = undefined;
+      return res;
+    };
+    // The plugin's own definition file, the plugin folder, a folder above it.
+    expect((await archive(['Plugins/GTM/mcp.json'])).status).toBe(200);
+    expect((await archive(['Plugins/GTM'])).status).toBe(200);
+    expect((await archive(['Plugins'])).status).toBe(200);
+    // A connector elsewhere: refused by name, before anything is read.
+    const refused = await archive(['Plugins/Other']);
+    expect(refused.status).toBe(403);
+    const body = (await refused.json()) as { error: string; code: string };
+    expect(body.code).toBe('not_available_to_connection');
+    expect(body.error).toContain('The plugin "GTM" is not available to this connection.');
+    // A narrowed connection with no resolver wired loads nothing.
+    expect((await archive(null)).status).toBe(403);
+  });
+
+  it('an out-of-scope plugin folder the person cannot read answers the 404 an absent one does', async () => {
+    const pluginDir = path.join(wsDir, KB, 'Plugins', 'Private');
+    await fs.mkdir(pluginDir, { recursive: true });
+    await fs.writeFile(path.join(pluginDir, 'mcp.json'), '{"mcpServers":{}}', 'utf-8');
+    const base = await baseUrl(undefined, { agentPath: OPS.path, agentScope: loading(['Plugins/Other']), readable: false });
+    const existing = await fetch(`${base}/api/agent/plugins/Private/archive`);
+    const absent = await fetch(`${base}/api/agent/plugins/Nowhere/archive`);
+    expect(existing.status).toBe(404);
+    expect(await existing.json()).toEqual(await absent.json());
+    expect(absent.status).toBe(404);
+  });
+
   it('zips a readable plugin folder', async () => {
     const pluginDir = path.join(wsDir, KB, 'Plugins', 'GTM');
     await fs.mkdir(pluginDir, { recursive: true });
@@ -119,3 +177,21 @@ describe('GET /agent/plugins/:folder/archive', () => {
     expect(await res.json()).toEqual({ error: 'Failed to archive plugin' });
   });
 });
+
+describe('GET /tools/:slug/manual', () => {
+  it("narrows an inline manual read to the connectors the connection's .agent file loads", async () => {
+    const resolveInlineManual = vi.fn(async () => ({ utcp_version: '1.1.0', manual_version: '1.0.0', tools: [] }));
+    const service = { resolveInlineManual } as unknown as IToolManualService;
+    // Everything asks exactly what it asked before: no narrowing at all.
+    let base = await baseUrl(undefined, undefined, service);
+    expect((await fetch(`${base}/api/tools/weather/manual`)).status).toBe(200);
+    expect(resolveInlineManual).toHaveBeenLastCalledWith('ali@example.com', 'weather', undefined);
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    base = await baseUrl(undefined, { agentPath: OPS.path, agentScope: loading(['Plugins/GTM']) }, service);
+    expect((await fetch(`${base}/api/tools/weather/manual`)).status).toBe(200);
+    const within = (resolveInlineManual.mock.calls.at(-1) as unknown[])[2] as { within: (p: string) => boolean };
+    expect(within.within('Plugins/GTM/weather.tool')).toBe(true);
+    expect(within.within('Plugins/Other/weather.tool')).toBe(false);
+  });
+});

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

@@ -183,6 +183,15 @@ describe('ToolManualService', () => {
     expect(manual).toBeNull();
   });
 
+  test("does not resolve a readable inline manual outside a connection's connectors", async () => {
+    // The narrowing applies after the read gate, on the manual's own path.
+    const paths: string[] = [];
+    const within = (p: string) => (paths.push(p), false);
+    expect(await svc().resolveInlineManual('user@x.eu', 'weather', { within })).toBeNull();
+    expect(paths).toEqual([expect.stringMatching(/weather\.tool$/)]);
+    expect(await svc().resolveInlineManual('user@x.eu', 'weather', { within: () => true })).not.toBeNull();
+  });
+
   test('resolves an inline tool that calls Google as a service account, and surfaces the key variable', async () => {
     // The auth block is what makes the call; the key it names has to reach the
     // secrets UI as a shared variable or nobody can store it.
@@ -486,6 +495,30 @@ describe('ToolManualService', () => {
     });
   });
 
+  /**
+   * A connection made as an `.agent` file narrows the catalog (`within`) —
+   * AFTER the read gate, on every read an agent surface makes, so it can take
+   * a manual away and never give one.
+   */
+  describe('narrowed to a connection’s connectors', () => {
+    const onlyBilling = (p: string) => p === 'Plugins/billing.tool';
+    const everything = () => true;
+
+    test('every agent-facing read answers only what is both readable and within', async () => {
+      const s = svc();
+      expect((await s.toManualCallTemplates('user@x.eu', { within: onlyBilling })).map((t) => t.name)).toEqual(['billing']);
+      expect((await s.listAccessibleCatalog('user@x.eu', onlyBilling)).tools.map((t) => t.name)).toEqual(['billing']);
+      expect(await s.catalogFingerprints('user@x.eu', onlyBilling)).toHaveLength(1);
+      expect(await s.listLocalOnly('user@x.eu', () => false)).toEqual([]);
+    });
+
+    test('an entry naming a manual the person may not read loads nothing for it', async () => {
+      const s = svc(denyBilling);
+      expect(await s.toManualCallTemplates('user@x.eu', { within: onlyBilling })).toEqual([]);
+      expect((await s.toManualCallTemplates('user@x.eu', { within: everything })).map((t) => t.name)).toEqual(['weather']);
+    });
+  });
+
   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, 'Plugins');
@@ -920,6 +953,15 @@ describe('ToolManualService.listDeclaredOnlyOnBranch', () => {
     ]);
   });
 
+  test("narrowed to a connection's connectors, after the read gate", async () => {
+    await writeMcpJson(draftWs, 'Ops', ['pager']);
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DRAFT, (p) => p.startsWith('Plugins/Ops/'))).toEqual([
+      { name: 'pager', path: 'Plugins/Ops/mcp.json', type: 'mcp' },
+    ]);
+    // Naming an unreadable declaration does not let it through.
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DRAFT, (p) => p.startsWith('Plugins/Secret Plugin/'))).toEqual([]);
+  });
+
   test('is empty for the default branch itself and for a branch without a workspace', async () => {
     expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DEFAULT_BRANCH)).toEqual([]);
     expect(await svc().listDeclaredOnlyOnBranch('user@example.com', 'user/gone')).toEqual([]);

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

@@ -273,7 +273,7 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
       note?: string;
     };
     // Resolved for the caller, on the branch they named.
-    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm');
+    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm', undefined);
     // The released catalog is unchanged — the draft's server is not in it...
     expect(body.tools.map((t) => t.slug)).not.toContain('crm');
     // ...and the agent is told where it is and what makes it live.
@@ -294,7 +294,7 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
     const res = await callSetup(base, agentToken);
     expect(res.status).toBe(200);
     const body = (await res.json()) as { onBranchOnly: { name: string; branch: string }[]; note?: string };
-    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm');
+    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm', undefined);
     expect(body.onBranchOnly).toEqual([
       { name: 'crm', path: 'Plugins/Sales/mcp.json', type: 'mcp', branch: 'alice/add-crm' },
     ]);
@@ -311,7 +311,7 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
       onBranchOnly: { name: string }[];
     };
     expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledTimes(1);
-    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm');
+    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm', undefined);
     expect(body.onBranchOnly.map((p) => p.name)).toEqual(['crm']);
   });
 

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

@@ -1,5 +1,8 @@
-export { ToolManualService } from './tool-manuals.service.js';
-export { PendingToolsService } from './pending-tools.service.js';
+// The services are types here: the composition root constructs them from
+// their files, so a module that imports this entry for a helper or a type
+// does not load the implementations.
+export type { ToolManualService } from './tool-manuals.service.js';
+export type { PendingToolsService } from './pending-tools.service.js';
 export { registerToolManualsTools } from './tool-manuals.tools.js';
 export {
   createToolManualsAgentRoutes,
@@ -7,6 +10,7 @@ export {
 } from './tool-manuals.routes.js';
 export {
   EXTERNAL_KB_MANUAL_NAME,
+  type ConnectorScope,
   type IPendingToolService,
   type IToolManualService,
   type PendingTool,
@@ -15,3 +19,9 @@ export {
   type ToolCapability,
   type ToolManualType,
 } from './tool-manuals.contract.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { judgeMcpServerEntry } from './mcp-json-discovery.js';
+export type { PortableHttpEntry, PortableStdioEntry } from './mcp-json-discovery.js';
+export { MAX_CAPABILITIES } from './tool-manuals.contract.js';
+export type { ToolHealthCheck, ToolManualDescriptor, ToolProbeTarget, ToolVariable } from './tool-manuals.contract.js';
+export { normalizeToolManual } from './tool-manuals.service.js';

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -6,12 +6,12 @@ import {
   PLUGIN_MCP_FILE,
   type AuthUser,
 } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { validatedVariables } from './mcp-json-discovery.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import { containsVariableReference, findReservedVariableRef } from '../../shared/variable-refs.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { IToolManualService, ToolVariable } from './tool-manuals.contract.js';
 

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

@@ -6,9 +6,9 @@ import {
   type IWorkflowService,
   type KbLayout,
 } from '@bevel-software/platform-shared';
-import { type WorkspaceService } from '../workspace/workspace.service.js';
+import { type WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { readAt, visibleProposedFiles } from '../../shared/pending-proposals.js';
 import { utcpNamespacePrefix } from '../../shared/utcp-namespace.js';
 import { baseName, normalizeToolManual } from './tool-manuals.service.js';

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

@@ -7,15 +7,14 @@ import {
   PLUGIN_MCP_FILE,
   type AuthUser,
 } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { utcpNamespacePrefix } from '../../shared/utcp-namespace.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { IFsProbe } from '../../shared/fs.contract.js';
-import type { ISkillService } from '../skills/skills.contract.js';
-import type { IPluginIndexService, PluginCatalogEntry } from '../plugins/plugins.contract.js';
-import type { PluginSource } from '../plugins/discovery/plugin-source.js';
-import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
+import type { ISkillService } from '../skills/index.js';
+import type { IPluginIndexService, PluginCatalogEntry, PluginSource } from '../plugins/index.js';
+import type { ISecretsVaultService } from '../secrets-vault/index.js';
 import type { IToolManualService, ToolManualSummary } from './tool-manuals.contract.js';
 
 /**

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

@@ -356,6 +356,16 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
   hiddenTools: HiddenTool[];
 }
 
+/**
+ * A connection's narrowing of the catalog: whether the connector defined at
+ * `definitionPath` (a `.tool` file, or the MCP server definition a server
+ * entry came from) is one the connection loads. Applied AFTER the caller's
+ * read gate, so it can only take manuals away. The agent surfaces pass the
+ * connection scope's `allowsConnector` (`modules/agent-scope`); absent is the
+ * whole readable catalog.
+ */
+export type ConnectorScope = (definitionPath: string) => boolean;
+
 export interface IToolManualService {
   /** The `.tool` manuals the user can read, as summaries. */
   listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
@@ -377,7 +387,7 @@ export interface IToolManualService {
    * unparseable by definition, so the verdict comes from its folder's
    * `access.md` chain — default-deny, as everywhere else.
    */
-  listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog>;
+  listAccessibleCatalog(userEmail: string, within?: ConnectorScope): Promise<AccessibleCatalog>;
   /**
    * 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
@@ -406,7 +416,7 @@ export interface IToolManualService {
    * manual's embedded tools breaks without touching anything a summary shows.
    * Opaque to callers: only equality is ever asked of these lines.
    */
-  catalogFingerprints(userEmail: string): Promise<string[]>;
+  catalogFingerprints(userEmail: string, within?: ConnectorScope): Promise<string[]>;
   /**
    * Every manual in the catalog, UNFILTERED by access — the mirror of
    * `skillService.listSkills(undefined)`. For caller-INDEPENDENT counting only
@@ -422,7 +432,7 @@ export interface IToolManualService {
    * NOT include the KB manual (the route prepends that). With `{ remoteOnly: true }`
    * (the remote MCP proxy), LOCAL-ONLY manuals (`remote: false`) are excluded.
    */
-  toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean }): Promise<CallTemplate[]>;
+  toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean; within?: ConnectorScope }): Promise<CallTemplate[]>;
   /**
    * The caller's accessible LOCAL-ONLY (`remote: false`) manuals.
    *
@@ -430,21 +440,23 @@ export interface IToolManualService {
    * both: `name` is the UTCP namespace its `${VAR}` refs are keyed by, and
    * `slug` is what addresses the manual on the variable-resolution route.
    */
-  listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]>;
+  listLocalOnly(userEmail: string, within?: ConnectorScope): Promise<{ slug: string; name: string; path: string }[]>;
   /**
    * Tools declared on `branch` whose namespace the default-branch catalog does
    * not serve yet, filtered to what the caller can read there. The catalog is
    * built from the default branch only, so a server an agent declares on its
    * draft is invisible to every tool surface until the draft is merged — this
    * is how the agent is told where its declaration lives. `[]` for the default
-   * branch itself, or a branch with no workspace.
+   * branch itself, or a branch with no workspace. `within` narrows the answer
+   * to a connection's connectors, after the read gate, as the catalog's does.
    */
   listDeclaredOnlyOnBranch(
     userEmail: string,
     branch: string,
+    within?: ConnectorScope,
   ): Promise<{ name: string; path: string; type: ToolManualType }[]>;
   /** The embedded UTCP manual for an inline `.tool` (served at `/api/tools/:slug/manual`). */
-  resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null>;
+  resolveInlineManual(userEmail: string, slug: string, opts?: { within?: ConnectorScope }): Promise<UtcpManualDict | null>;
   /** Validate a draft `.tool` file's content for the renderer preview. */
   preview(content: string): Promise<ToolManualPreview>;
   /**

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

@@ -5,20 +5,21 @@ const log = logger('tool-manuals');
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import AdmZip from 'adm-zip';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { isAbsence, type IFsProbe, type ITreeWalker } from '../../shared/fs.contract.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import type { IPluginIndexService } from '../plugins/plugins.contract.js';
+import type { IAccessControl } from '../access/index.js';
+import type { IPluginIndexService } from '../plugins/index.js';
 import '@utcp/http'; // side effect: register the 'http' call-template type
 import { CallTemplateSerializer, type CallTemplate } from '@utcp/sdk';
 import { type IPendingToolService, type IToolManualService, EXTERNAL_KB_MANUAL_NAME } from './tool-manuals.contract.js';
 import { McpServerEditError, type McpServerEditService, type McpServerWrite } from './mcp-server-edit.service.js';
 import { ToolDeleteError, type ToolDeleteService } from './tool-delete.service.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
-import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
+import '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
+import '../tool-auth/index.js'; // Express Request augmentation (req.toolAuth)
 import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { NOT_AVAILABLE_TO_CONNECTION, resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 
 /** Resolve a connection-key/internal-token user id to its email (per-caller ACL). */
 export type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
@@ -64,6 +65,11 @@ export function createToolManualsAgentRoutes(
      */
     pluginIndex?: Pick<IPluginIndexService, 'catalog'>;
   },
+  /**
+   * Resolves the scope of a connection made as an agent configuration, so
+   * `all-tools` lists only the connectors it loads (`modules/agent-scope`).
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -83,9 +89,18 @@ export function createToolManualsAgentRoutes(
       // Default remote-safe: exclude local-only manuals unless the caller (a locally
       // installed MCP server) explicitly opts in with `?remote=false`.
       const remoteOnly = req.query.remote !== 'false';
-      const userManuals = email ? await toolManualService.toManualCallTemplates(email, { remoteOnly }) : [];
+      // A connection made as an agent configuration lists only the connectors that
+      // file loads, and says which agent it is — the MCP proxy words its
+      // refusals and its handshake from that. Everything lists as it always
+      // did, with no `connection` at all.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      const within = scope.connectorFilter();
+      const userManuals = email
+        ? await toolManualService.toManualCallTemplates(email, within ? { remoteOnly, within } : { remoteOnly })
+        : [];
       const manuals: CallTemplate[] = [kbManualTemplate(), ...userManuals];
-      res.json({ manuals });
+      const connection = scope.toWire();
+      res.json(connection ? { manuals, connection } : { manuals });
     } catch (err) {
       log.error('all-tools failed:', { err });
       res.status(500).json({ error: 'Failed to list tools' });
@@ -171,6 +186,24 @@ export function createToolManualsAgentRoutes(
         email,
         rels.map((r) => `${pluginRel}/${r}`),
       );
+      // A folder with nothing the person may read is absent to them, whatever
+      // the connection — so that 404 comes first, and the connection's own
+      // refusal below never confirms a folder the person could not see.
+      if (![...verdicts.values()].some((v) => v === true)) {
+        return void res.status(404).json({ error: 'Not found' });
+      }
+      // A connection made as an agent configuration materializes only a plugin
+      // that defines a connector the file loads — the archive is how the
+      // local MCP server runs one, and nothing else asks for it. Checked
+      // before any file is opened.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      if (!scope.loadsConnectorIn(pluginRel)) {
+        const why = scope.describe();
+        return void res.status(403).json({
+          error: `The plugin "${folder}" is not available to this connection.${why ? ` ${why}` : ''}`,
+          code: NOT_AVAILABLE_TO_CONNECTION,
+        });
+      }
       const zip = new AdmZip();
       let included = 0;
       let bytes = 0;
@@ -269,7 +302,11 @@ export function createToolManualsAgentRoutes(
       const email = await callerEmail(req);
       if (!email) return void res.status(403).json({ error: 'Forbidden' });
       const slug = Array.isArray(req.params.slug) ? req.params.slug[0] : req.params.slug;
-      const manual = await toolManualService.resolveInlineManual(email, String(slug));
+      // A connection made as an agent configuration reads only the manuals of the
+      // connectors it loads; another is as absent as one the person cannot read.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      const within = scope.connectorFilter();
+      const manual = await toolManualService.resolveInlineManual(email, String(slug), within ? { within } : undefined);
       if (!manual) return void res.status(404).json({ error: 'Not found' });
       res.json(manual);
     } catch (err) {