@bevel-software/platform-core-backend 0.33.0 → 0.35.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__/agent-roles-write.test.ts

@@ -4,21 +4,27 @@ import os from 'node:os';
 import path from 'node:path';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it } 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 { ToolRegistry } from '../../tool-registry/index.js';
+import {
+  InternalTokenService,
+  RoutineWritePolicyService,
+  WorkflowHooks,
+  createToolAuthMiddleware,
+  loadActiveGroups,
+  registerWorkspaceTools,
+} from '../../../__tests__/tool-wiring.js';
 import { createToolContextResolver } from '../tool-context.js';
 import { createToolHandlerFactory } from '../tool-handler.js';
-import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
-import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
-import { SpillStore } from '../../workspace/spill-store.js';
-import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
-import { NEW_ROLE_GUIDANCE } from '../../access-model/roles-yaml-guard.js';
-import { loadActiveGroups } from '../../access/access-control.service.js';
+import { DocExtractService, SpillStore, ToolDescriptionNotes, WorkerDocumentExtractor } from '../../workspace/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
+/**
+ * The sentence a refused role creation carries to the agent, as the agent
+ * guide states it too: asserted as the words a person reads, not as the
+ * module's constant, so a reworded refusal is a visible change here.
+ */
+const NEW_ROLE_GUIDANCE = 'add people to existing roles, and use a GROUP for a task- or team-scoped set of people';
+
 /**
  * The agent's file tools over the production context resolver and a real
  * workspace on disk: a roles.yaml write that creates a role is refused with a
@@ -71,6 +77,8 @@ async function start(): Promise<string> {
     canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
     // The `after` half of a move's or copy's preview — allowing everything, like the gates above.
     previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
+    // Who else loses or gains access in a move: nobody, here.
+    prospectiveHolderChanges: async () => ({ lose: [], gain: [] }),
   } as never;
   registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache, new WorkerDocumentExtractor()), allowAll, testKbContext({ kbDirName: KB }), {
     // No hook registered: the agent-access gate refuses nothing here.

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/__tests__/route-tool-schemas.catalog.test.ts

@@ -0,0 +1,38 @@
+import { compileCheck, exampleArguments } from '@bevel-software/platform-mcp-core';
+import { describe, expect, it } from 'vitest';
+import { hexisCatalog } from '../../../__tests__/hexis-catalog.js';
+import { routeToolSchemas } from '../route-tool-schemas.js';
+
+/**
+ * Every tool a route mounts declares two schemas: the one a client sees
+ * (`inputs`, with the platform tools' arguments under `body`) and the FLAT one
+ * the route itself checks a call against. The `Call:` line at the top of each
+ * description is generated from the first; the route refuses by the second.
+ * The two must agree, or a call written from the example is refused one
+ * layer in, with nothing in the description to say why.
+ *
+ * Held here, over the whole catalog Hexis registers, because the flat schema
+ * is this module's: `routeToolSchemas` is how a mounted route finds its own,
+ * and no other module reads it.
+ */
+describe('the flat schema a route checks against accepts the call its own example shows', () => {
+  it('for every tool Hexis mounts on a route', async () => {
+    const { internal } = await hexisCatalog();
+    const mounted = internal.filter((tool) => routeToolSchemas(tool.name) !== undefined);
+    // The catalog is the real one: the family every scenario names is in it.
+    for (const name of ['read_file', 'write_file', 'list_files', 'grep', 'move_file']) {
+      expect(mounted.some((t) => t.name === name), name).toBe(true);
+    }
+    expect(mounted.length).toBeGreaterThan(12);
+    for (const tool of mounted) {
+      // The client's schema is the flat one in its envelope (`bodyEnvelope`),
+      // so the client's example and the route's check meet on the flat schema:
+      // an example written from it must pass the check made from it.
+      const flat = routeToolSchemas(tool.name)!.flat;
+      const check = compileCheck(flat);
+      expect(check.checkable, `${tool.name} (flat): ${check.checkable ? '' : check.reason}`).toBe(true);
+      if (!check.checkable) throw new Error(check.reason);
+      expect(check.check(exampleArguments(flat)), `${tool.name} (flat)`).toEqual([]);
+    }
+  });
+});

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-def.ts

@@ -16,7 +16,7 @@ const toolSerializer = new ToolSerializer();
 export const BRANCH_INPUT: JsonSchema = {
   type: 'string',
   minLength: 1,
-  description: 'The branch (draft) whose workspace this operates on — pass the branch you are currently working on.',
+  description: 'The branch to work on: the default branch (`get_agent_guide` names it) or your draft.',
 };
 
 /**

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);
+  });
+});