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

package/src/modules/tool-auth/internal-token.service.ts

@@ -47,6 +47,15 @@ export interface InternalTokenClaim {
    * internal token.
    */
   connectionId?: string;
+  /**
+   * The agent configuration the external caller's connection was made as (a
+   * repo-relative knowledge-base path), copied at mint from the verified
+   * grant or connection — the hosted proxy's loopback token and the local
+   * server's exchanged grant both carry it, so every agent surface narrows
+   * their calls to that agent's scope (`modules/agent-scope`). Absent is
+   * Everything. Carried, never decided, like `connectionId`.
+   */
+  agentPath?: string;
 }
 
 interface SignedPayload extends InternalTokenClaim {
@@ -148,6 +157,7 @@ export class InternalTokenService {
       ...(typeof payload.focusedBranch === 'string' ? { focusedBranch: payload.focusedBranch } : {}),
       ...(payload.externalProxy === true ? { externalProxy: true } : {}),
       ...(typeof payload.connectionId === 'string' ? { connectionId: payload.connectionId } : {}),
+      ...(typeof payload.agentPath === 'string' && payload.agentPath ? { agentPath: payload.agentPath } : {}),
     };
   }
 

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -47,6 +47,13 @@ export interface ToolAuth {
    * recorder attributes a direct tool call to.
    */
   connectionId?: string;
+  /**
+   * The agent configuration an EXTERNAL caller's connection was made as — a
+   * connection key's `api_tokens.agent_path`, or the one an `externalProxy`
+   * token carries for an agent connection. Absent is Everything. Every agent
+   * surface resolves it to the connection's scope (`modules/agent-scope`).
+   */
+  agentPath?: string;
   /** Always `'write'` now (the middleware sets it for both internal + external — neither credential carries scope). The read path is dormant until consumer agents are removed. */
   scope: 'read' | 'write';
 }
@@ -114,6 +121,14 @@ export type VerifyResult =
   | { ok: true; auth: ToolAuth }
   | { ok: false; status: number; message: string; challenge?: string };
 
+/**
+ * A live agent connection's current "Connect as" choice, or null when it is
+ * gone or revoked — what `BevelOAuthProvider.liveConnectionChoice` answers.
+ */
+export interface ConnectionChoices {
+  liveConnectionChoice(connectionId: string): Promise<{ agentPath: string | null } | null>;
+}
+
 /**
  * The framework-agnostic verify core: bearer token (the value AFTER `Bearer `) →
  * normalized `ToolAuth`, accepting EITHER a `bevel_…` connection key (external —
@@ -135,6 +150,14 @@ export function createTokenVerifier(
    * it; absent, internal tokens are judged on their signature alone.
    */
   accounts?: Pick<AuthService, 'isActive'>,
+  /**
+   * Where an `externalProxy` token that names an agent connection reads the
+   * connection's CURRENT choice: the token outlives a re-consent, so the
+   * agent it was minted with may no longer be the one chosen. A
+   * connection no longer live (revoked, deleted) refuses the token. Absent,
+   * the token's own choice stands.
+   */
+  connections?: ConnectionChoices,
 ): (token: string | undefined) => Promise<VerifyResult> {
   const missing = { ok: false as const, status: 401, message: 'A connection key or internal token is required' };
   return async (token) => {
@@ -152,6 +175,13 @@ export function createTokenVerifier(
       if (accounts && !(await accounts.isActive(claim.userId))) {
         return { ok: false, status: 401, message: ACCOUNT_DEACTIVATED_MESSAGE };
       }
+      let agentPath = claim.agentPath;
+      if (claim.externalProxy && claim.connectionId && connections) {
+        const live = await connections.liveConnectionChoice(claim.connectionId);
+        // A revoked connection's token is dead here too, as it is at the MCP endpoint.
+        if (!live) return { ok: false, status: 401, message: 'Access for this agent was revoked' };
+        agentPath = live.agentPath ?? undefined;
+      }
       return claim.externalProxy
         ? {
             ok: true,
@@ -159,6 +189,7 @@ export function createTokenVerifier(
               source: 'external',
               userId: claim.userId,
               ...(claim.connectionId ? { connectionId: claim.connectionId } : {}),
+              ...(agentPath ? { agentPath } : {}),
               scope: 'write',
             },
           }
@@ -169,7 +200,16 @@ export function createTokenVerifier(
     if (externalApiKeyService.looksLikeExternalApiKey(token)) {
       const resolved = await externalApiKeyService.verifyAndLoadToken(token);
       if (resolved) {
-        return { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } };
+        return {
+          ok: true,
+          auth: {
+            source: 'external',
+            userId: resolved.user.id,
+            tokenId: resolved.tokenId,
+            ...(resolved.agentPath ? { agentPath: resolved.agentPath } : {}),
+            scope: 'write',
+          },
+        };
       }
       // A live key of a switched-off account is told so, not sent to mint another.
       if (await externalApiKeyService.isKeyOfSwitchedOffAccount?.(token)) {
@@ -192,8 +232,9 @@ export function createToolAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
   accounts?: Pick<AuthService, 'isActive'>,
+  connections?: ConnectionChoices,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, accounts);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, accounts, connections);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -233,8 +274,9 @@ export function createManualAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
   authService: Pick<AuthService, 'isActive' | 'resolveSession'>,
+  connections?: ConnectionChoices,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, authService, connections);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {

package/src/modules/tool-helpers/__tests__/can-write.tools.test.ts

@@ -24,7 +24,9 @@ import { NodeFs } from '../../kb-fs/node-fs.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { BranchNotFoundError } from '../../../shared/domain-errors.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import { SkillService, registerSkillsTools } from '../../skills/index.js';
+import { registerSkillsTools } from '../../skills/index.js';
+// The service itself, from its file: the module entry offers it as a type only.
+import { SkillService } from '../../skills/skills.service.js';
 import { defaultBranchWriteVerdicts } from '../index.js';
 
 /**

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

@@ -17,6 +17,7 @@ import type { WorkflowEventBus } from '../workflow/index.js';
 import type { AuthService } from '../auth/index.js';
 import { ToolError, type ToolContext } from './tool.contract.js';
 import type { ToolAuth } from '../tool-auth/index.js';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 
 export interface ToolContextDeps {
   authService: AuthService;
@@ -40,6 +41,12 @@ export interface ToolContextDeps {
   loadActiveGroups?: (
     read: (filename: string) => Promise<string | null>,
   ) => Promise<{ groups: GroupsIndex; sourceFile: string; health: { ok: boolean } }>;
+  /**
+   * Resolves the scope of a connection made as an agent configuration. Every
+   * deployment passes it. Absent, a credential that names an agent loads
+   * nothing — a narrowing that cannot be read is never read as Everything.
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>;
 }
 
 /** A file's text, or null when it does not exist. Any other failure throws. */
@@ -149,9 +156,12 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       return fs;
     };
 
+    const connectionScope = await resolveConnectionScope(deps.agentScope, user.email, auth.agentPath);
+
     return {
       user,
       scope: auth.scope,
+      connectionScope,
       source: auth.source,
       tokenId: auth.tokenId,
       // For `internal` callers the signed token claim is the ONLY trustworthy

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

@@ -13,6 +13,8 @@ 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 { 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
 
@@ -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,4 +1,5 @@
 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/index.js';
 import type { WorkflowEventBus } from '../workflow/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,4 +1,4 @@
-import type { IExternalApiKeyService, InternalTokenService } from '../tool-auth/index.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';
@@ -6,6 +6,8 @@ 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;
 }
 
 /**
@@ -34,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,

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>;
   /**