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

package/src/modules/plugins/plugin-links.ts

@@ -58,10 +58,27 @@ export const LINK_GRANT_VERBS = ['read', 'write'] as const;
 export interface LinkMembership {
   /** skill path → every plugin that holds it, inline or by link. */
   bySkill: Map<string, PluginMembership[]>;
-  /** plugin folder → its links. Every plugin folder appears, linked or not. */
+  /**
+   * plugin identity (`PluginLinks.name`) → its links. Every plugin appears,
+   * linked or not. A name and a folder may differ, so a repository path is
+   * read from the value's `folder`, never from the key.
+   */
   byPlugin: Map<string, PluginLinks>;
 }
 
+/**
+ * What a reader of the link index asks it — the contract a consumer outside
+ * this module (a distribution's agent-scope resolver, through
+ * `CorePorts.agentScope`) is written against. Dropping the cache is the
+ * index owner's affair, not a reader's, so it is not here.
+ */
+export interface IPluginLinkIndex {
+  /** Every plugin's links and every skill's memberships, from the released catalog. */
+  membership(): Promise<LinkMembership>;
+  /** The memberships of one skill (empty when it is in no plugin). */
+  pluginsOf(skillPath: string): Promise<PluginMembership[]>;
+}
+
 /**
  * The link index: which shared skills each plugin links, and — the other way
  * round — which plugins each skill belongs to, whether by sitting inside the
@@ -88,7 +105,7 @@ export interface LinkMembership {
  * subscriber that drops the plugin index, so a link committed on the default
  * branch shows within one round-trip.
  */
-export class PluginLinkIndex {
+export class PluginLinkIndex implements IPluginLinkIndex {
   private readonly cache: TtlCache<LinkMembership>;
 
   constructor(

package/src/modules/plugins/plugins.routes.ts

@@ -17,6 +17,8 @@ import { pluginFolderBelowRoot } from './plugins.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { PluginProvisionError, type PluginProvisionService } from './plugin-provision.service.js';
 import { argumentsRefusal } from '../tool-helpers/index.js';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
+import '../tool-auth/index.js'; // Express Request.toolAuth augmentation
 import { PluginLinkError, type PluginLinksService } from './plugin-links.service.js';
 import { PluginRenameError, type PluginRenameService } from './plugin-rename.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
@@ -83,6 +85,29 @@ function refuseMismatchedArguments(req: express.Request, res: express.Response):
   return true;
 }
 
+/**
+ * Answer the connection-scope refusal when the caller's connection was made
+ * as an agent configuration that does not list `toolName`; `true` when it answered.
+ * These routes ARE the `create_plugin` and `my_plugin` tools but are not
+ * hosted by `toolHandler`, so they ask the one policy it asks —
+ * `ConnectionScope.platformToolRefusal` — and answer what it answers. A
+ * session, or a key made as Everything, carries no `agentPath` and is never
+ * refused.
+ */
+async function refuseOutsideConnectionScope(
+  req: express.Request,
+  res: express.Response,
+  user: AuthUser,
+  toolName: string,
+  agentScope: Pick<IAgentScopeResolver, 'resolve'> | undefined,
+): Promise<boolean> {
+  const scope = await resolveConnectionScope(agentScope, user.email, req.toolAuth?.agentPath);
+  const refusal = scope.platformToolRefusal(toolName);
+  if (!refusal) return false;
+  res.status(403).json(refusal);
+  return true;
+}
+
 /**
  * The two doors through which plugin folders come to exist — ONE
  * implementation each, for the app and for agents alike:
@@ -106,6 +131,8 @@ function refuseMismatchedArguments(req: express.Request, res: express.Response):
 export function createPluginCreationRoutes(
   provision: Pick<PluginProvisionService, 'createPlugin' | 'ensurePersonalPlugin'>,
   resolveUser: (req: express.Request) => Promise<AuthUser | null>,
+  /** Resolves a connection's agent choice to its scope; absent, a narrowed connection loads nothing. */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -117,8 +144,10 @@ export function createPluginCreationRoutes(
     }
     // These two routes ARE the `create_plugin` and `my_plugin` tools, so an
     // agent's call is checked against what those tools declare, exactly as a
-    // route-hosted tool's is in `toolHandler`: a call that does not match is
-    // refused before anything is provisioned.
+    // route-hosted tool's is in `toolHandler`: a call that does not match, or
+    // a connection whose agent does not list the tool, is refused before
+    // anything is provisioned.
+    if (await refuseOutsideConnectionScope(req, res, user, 'create_plugin', agentScope)) return;
     if (refuseMismatchedArguments(req, res)) return;
     // `req.body` is undefined when no JSON body was sent at all — that is a
     // 400, not a destructuring crash.
@@ -155,8 +184,10 @@ export function createPluginCreationRoutes(
     }
     // These two routes ARE the `create_plugin` and `my_plugin` tools, so an
     // agent's call is checked against what those tools declare, exactly as a
-    // route-hosted tool's is in `toolHandler`: a call that does not match is
-    // refused before anything is provisioned.
+    // route-hosted tool's is in `toolHandler`: a call that does not match, or
+    // a connection whose agent does not list the tool, is refused before
+    // anything is provisioned.
+    if (await refuseOutsideConnectionScope(req, res, user, 'my_plugin', agentScope)) return;
     if (refuseMismatchedArguments(req, res)) return;
     try {
       res.json(await provision.ensurePersonalPlugin(user));

package/src/modules/secrets-vault/__tests__/connect-pending.route.test.ts

@@ -3,6 +3,7 @@ import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
 import { createSecretsVaultRoutes } from '../secrets-vault.routes.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { ConnectionScope } from '../../agent-scope/index.js';
 
 /**
  * The aggregated `/connect/pending` surface: everything standing between the
@@ -336,6 +337,118 @@ describe('GET /api/connect/pending — readability', () => {
   });
 });
 
+describe('GET /api/connect/pending — narrowed to the agent the connection is made as', () => {
+  /**
+   * The consent step's "Connect as" choice: a connection made as an `.agent`
+   * file loads only the connectors the file lists, so the page that asks for
+   * sign-ins and keys lists only those. Two readable tools, one of which the
+   * agent loads; the agent is answered by a stub resolver over the REAL
+   * `ConnectionScope`, the one answer every agent surface asks.
+   */
+  const AGENT = { path: 'Agents/ops.agent', name: 'ops' };
+  const resolver = {
+    resolve: async (_email: string | undefined, agentPath: string | null | undefined) => {
+      if (!agentPath) return ConnectionScope.everything();
+      if (agentPath === AGENT.path) {
+        return ConnectionScope.narrowed(AGENT, { skills: [], connectors: ['Tools/weather.tool'], platformTools: null }, 'fp');
+      }
+      return ConnectionScope.gone(agentPath);
+    },
+  };
+  const twoTools = {
+    listAccessible: async () => [
+      {
+        slug: 'weather',
+        name: 'weather',
+        path: 'Tools/weather.tool',
+        type: 'http' as const,
+        variables: [{ name: 'API_KEY', scope: 'user' as const, label: null }],
+      },
+      {
+        slug: 'notion',
+        name: 'notion',
+        path: 'Tools/notion.tool',
+        type: 'mcp' as const,
+        variables: [
+          {
+            name: 'MCP_OAUTH',
+            scope: 'user' as const,
+            label: 'notion sign-in',
+            oauth: { authorizationUrl: 'https://a.example/auth', tokenUrl: 'https://a.example/token', clientId: 'cid' },
+          },
+        ],
+      },
+    ],
+  } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
+  const vault = {
+    statusFor: async (_u: string, keys: string[]) =>
+      keys.map((key) => ({
+        key,
+        adminConfigured: key === 'notion_MCP_OAUTH',
+        adminKind: key === 'notion_MCP_OAUTH' ? ('oauth' as const) : null,
+        userConfigured: false,
+        userKind: null,
+      })),
+    // A sign-in registered directly on the Secrets page: nobody's connector.
+    list: async () => [
+      { id: 's-own', key: 'MY_TOKEN', kind: 'oauth' as const, label: 'Mine', authorized: false, createdAt: new Date(), updatedAt: new Date() },
+    ],
+  } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
+
+  async function pendingAs(agent: string | null, withResolver = true) {
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      req.userId = 'u1';
+      req.userEmail = 'a@x.com';
+      next();
+    });
+    app.use(
+      '/api',
+      createSecretsVaultRoutes({
+        kb: testKbContext(),
+        secretsVault: vault,
+        toolManualService: twoTools,
+        accessControl,
+        ...(withResolver ? { agents: resolver } : {}),
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
+        stateSecret: 'test-secret',
+        publicBackendUrl: 'http://localhost:3000',
+        publicFrontendUrl: 'http://localhost:5173',
+      }),
+    );
+    httpServer = await new Promise<HttpServer>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    const port = (httpServer.address() as { port: number }).port;
+    const query = agent === null ? '' : `?agent=${encodeURIComponent(agent)}`;
+    const res = await fetch(`http://127.0.0.1:${port}/api/connect/pending${query}`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as PendingBody & { toolOAuth: { slug: string }[] };
+    return { tools: body.tools.map((t) => t.slug), signIns: body.toolOAuth.map((o) => o.slug), standalone: body.oauth.map((o) => o.id) };
+  }
+
+  it('lists everything without a choice, as before', async () => {
+    expect(await pendingAs(null)).toEqual({ tools: ['weather'], signIns: ['notion'], standalone: ['s-own'] });
+  });
+
+  it('lists only the connectors the agent loads, and no standalone sign-in', async () => {
+    expect(await pendingAs(AGENT.path)).toEqual({ tools: ['weather'], signIns: [], standalone: [] });
+  });
+
+  it('lists nothing for an agent the person cannot use: a narrowing that cannot be read is never Everything', async () => {
+    expect(await pendingAs('Agents/gone.agent')).toEqual({ tools: [], signIns: [], standalone: [] });
+    // …and the same with no resolver wired at all.
+    expect(await pendingAs(AGENT.path, false)).toEqual({ tools: [], signIns: [], standalone: [] });
+  });
+
+  it('reads an empty or blank choice as Everything', async () => {
+    expect(await pendingAs('  ')).toEqual({ tools: ['weather'], signIns: ['notion'], standalone: ['s-own'] });
+  });
+});
+
 describe('GET /api/connect/pending — OAuth scope coverage', () => {
   // A tool with an OAuth-backed var that now requires two scopes.
   const oauthTool = {

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -17,10 +17,19 @@ import type { IConnectionProbeService } from '../connection-probe/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IAccessControl } from '../access/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 import '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface SecretsVaultRoutesDeps {
   secretsVault: ISecretsVaultService;
+  /**
+   * Resolves what a connection made as an agent configuration loads, so the connect
+   * page can list only the tools the chosen agent would reach (`?agent=`).
+   * Optional: a construction without one answers such a request as a
+   * connection that loads nothing — a narrowing that cannot be read is never
+   * read as Everything.
+   */
+  agents?: Pick<IAgentScopeResolver, 'resolve'>;
   /** The released branch's clone — where the `.tool` files the access verdicts are read from live. */
   kb: Pick<KbContext, 'defaultWorkspaceId'>;
   /** Source of `.tool` manuals + their declared variable scopes (default-branch catalog). */
@@ -267,12 +276,21 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
   // that is already set is nobody's outstanding work, so it is dropped. What is
   // not relaxed is readability: the listing is still built from `listAccessible`,
   // so a tool the caller may not read is named here in no state at all.
+  //
+  // `?agent=<path>` — the consent step's "Connect as" choice — narrows the
+  // listing to what a connection made as that agent configuration would load, by the
+  // ONE answer every agent surface asks (`ConnectionScope.allowsConnector`,
+  // applied after the read gate exactly as the tool listing applies it). A
+  // sign-in the connection will never reach is not on a page about what the
+  // connection needs. Absent, the listing is Everything's, as it always was.
   router.get('/connect/pending', async (req, res) => {
     const userId = req.userId;
     const email = req.userEmail;
     if (!userId || !email) return void res.status(401).json({ error: 'Not authenticated' });
     try {
-      const manuals = await toolManualService.listAccessible(email);
+      const agentPath = typeof req.query.agent === 'string' && req.query.agent.trim() !== '' ? req.query.agent : null;
+      const scope = await resolveConnectionScope(deps.agents, email, agentPath);
+      const manuals = (await toolManualService.listAccessible(email)).filter((m) => scope.allowsConnector(m.path));
       // BOTH tiers now — the workspace values are reported as well, so their
       // stored state has to be asked for.
       const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
@@ -371,9 +389,11 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       // Secrets page. A TOOL sign-in provisions a per-user row in the same
       // table (keyed `<manual>_<VAR>`), so exclude every tool-var key here or
       // an authorized tool sign-in would render twice — once as a toolOAuth
-      // row and again as a "standalone" one.
+      // row and again as a "standalone" one. They belong to no connector, so
+      // a connection narrowed to an agent's connectors has nothing to do with
+      // them: listed for Everything only.
       const toolOAuthKeys = new Set(toolOAuth.map((o) => o.key));
-      const secrets = await secretsVault.list(userId);
+      const secrets = scope.isEverything() ? await secretsVault.list(userId) : [];
       const oauth = secrets
         .filter((s) => s.kind === 'oauth' && !toolOAuthKeys.has(s.key))
         .map((s) => ({ id: s.id, key: s.key, label: s.label, authorized: s.authorized ?? false }));

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -280,6 +280,40 @@ describe('SkillService', () => {
     expect(await svc(denyRfi).getSkill('user@x.eu', 'rfi')).toEqual({ ok: false, error: 'forbidden' });
   });
 
+  /**
+   * A connection made as an `.agent` file narrows the skills (`within`) —
+   * AFTER the person's read gate, so it can take a skill away and never give
+   * one: a skill its lists name that the person may not read stays out.
+   */
+  describe('narrowed to a connection’s skills', () => {
+    const denyGuidelines = {
+      canRead: async () => true,
+      canReadBatch: async (_w: string, _e: string, paths: string[]) =>
+        new Map(paths.map((p) => [p, !p.startsWith('Plugins/Development/')])),
+    } as unknown as IAccessControl;
+    const everyPluginSkill = (folder: string) => folder.startsWith('Plugins/');
+
+    test('lists only what is both readable and within, and loads nothing else', async () => {
+      const list = await svc(denyGuidelines).listSkills('user@x.eu', { within: everyPluginSkill });
+      expect(list.map((s) => s.name)).toEqual(['rfi']);
+      expect(await svc().listSkills('user@x.eu', { within: (p) => p === 'Plugins/Development/coding-guidelines' })).toEqual([
+        expect.objectContaining({ name: 'coding-guidelines' }),
+      ]);
+    });
+
+    test('getSkill outside it is not there for the connection; inside it, the read gate still answers', async () => {
+      expect(await svc().getSkill('user@x.eu', 'rfi', undefined, { within: () => false })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      const inside = await svc().getSkill('user@x.eu', 'rfi', undefined, { within: everyPluginSkill });
+      expect(inside.ok).toBe(true);
+      expect(
+        await svc(denyGuidelines).getSkill('user@x.eu', 'coding-guidelines', undefined, { within: everyPluginSkill }),
+      ).toEqual({ ok: false, error: 'forbidden' });
+    });
+  });
+
   /**
    * The listing and the loader must never disagree about the same skill at the
    * same instant.

package/src/modules/skills/index.ts

@@ -1,5 +1,8 @@
-export { SkillService } from './skills.service.js';
-export { PendingSkillsService } from './pending-skills.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 { SkillService } from './skills.service.js';
+export type { PendingSkillsService } from './pending-skills.service.js';
 export { registerSkillsTools } from './skills.tools.js';
 export { createSkillsRoutes } from './skills.routes.js';
 export { AllowedToolsChecker } from './allowed-tools-check.js';
@@ -14,7 +17,9 @@ export type {
   PendingSkill,
   GetSkillResult,
   GetSkillOptions,
+  ListSkillsOptions,
   SkillHistorySource,
+  SkillScope,
 } from './skills.contract.js';
 // Reached by other modules; exported here so they stop importing the files.
 export type { PluginMembership } from './skills.contract.js';

package/src/modules/skills/skills.contract.ts

@@ -119,8 +119,19 @@ export interface ListSkillsOptions {
    * carries `unmerged: true` and this branch name: nobody approved it.
    */
   branch?: string;
+  /** Narrow the listing to a connection's skills — see {@link SkillScope}. */
+  within?: SkillScope;
 }
 
+/**
+ * A connection's narrowing of the skills: whether the skill in `skillFolder`
+ * (repo-relative) is one the connection loads. Applied AFTER the caller's read
+ * gate, so it can only take skills away. The agent surfaces pass the
+ * connection scope's `allowsSkill` (`modules/agent-scope`); absent is every
+ * skill the caller may read.
+ */
+export type SkillScope = (skillFolder: string) => boolean;
+
 /** What `getSkill` may be asked beyond a name and a file. */
 export interface GetSkillOptions {
   /**
@@ -152,6 +163,12 @@ export interface GetSkillOptions {
    * combination has exactly one sensible meaning.
    */
   branch?: string;
+  /**
+   * Narrow to a connection's skills — see {@link SkillScope}. A skill outside
+   * it answers `not_found`, as a name nobody used does: to this connection it
+   * is not there.
+   */
+  within?: SkillScope;
 }
 
 /**

package/src/modules/skills/skills.service.ts

@@ -108,7 +108,9 @@ export class SkillService implements ISkillService {
 
   async listSkills(userEmail?: string, options: ListSkillsOptions = {}): Promise<SkillSummary[]> {
     const { catalog, branch } = await this.catalogFor(options.branch);
-    const visible = userEmail ? await this.readableSkills(catalog, userEmail) : catalog.skills;
+    const readable = userEmail ? await this.readableSkills(catalog, userEmail) : catalog.skills;
+    const within = options.within;
+    const visible = within ? readable.filter((s) => within(s.summary.path)) : readable;
     if (branch === undefined) return visible.map((s) => s.summary);
     // Marking reads both copies of a folder, so it happens only here, on a
     // branch read that asked for it — the released catalog every other surface
@@ -135,6 +137,8 @@ export class SkillService implements ISkillService {
     // A skill the branch deleted is not a skill as far as this answer goes:
     // the same `not_found` a name nobody ever used gets.
     if (!found) return { ok: false, error: 'not_found' };
+    // Outside the connection's skills: not there, for this connection.
+    if (options.within && !options.within(found.summary.path)) return { ok: false, error: 'not_found' };
 
     // Through `readable`, not a bare `canRead`: the two gates must never
     // disagree. `canRead` reads a file's own frontmatter rules off disk on

package/src/modules/skills/skills.tools.ts

@@ -4,7 +4,7 @@ import type { IToolRegistry, JsonSchema, UtcpTool } from '../tool-registry/index
 import { TOOL_DESCRIPTION_CAP, GUIDE_FIRST_SENTENCE } from '../tool-registry/index.js';
 import { ToolError, type ToolContext, toolDef, bodyEnvelope, declareRouteTool, CAN_WRITE_CLAUSE, defaultBranchWriteVerdicts, type DefaultBranchWriteDeps } from '../tool-helpers/index.js';
 import type { ToolHandlerFactory } from '../tool-helpers/index.js';
-import type { ISkillService } from './skills.contract.js';
+import type { ISkillService, SkillScope } from './skills.contract.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';
 
@@ -130,9 +130,13 @@ export function registerSkillsTools(
     return { paths: committed.includes(skillMdOf(loaded)) ? committed : [skillMdOf(loaded), ...loaded.files], at };
   };
 
-  registry.registerExternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
+  registry.registerExternalTool((ctx) =>
+    buildListSkillsDef(skillService, ctx.userEmail, ctx.connectionScope?.skillFilter()),
+  );
   registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
-  registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+  registry.registerExternalTool((ctx) =>
+    buildGetSkillDef(skillService, ctx.userEmail, ctx.connectionScope?.skillFilter()),
+  );
   registry.registerInternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
   // Both defs are built per catalog listing (their descriptions name the skills
   // THIS caller may read), so declare the arguments here as well: a direct REST
@@ -140,17 +144,24 @@ export function registerSkillsTools(
   declareRouteTool('list_skills', LIST_SKILLS_INPUTS);
   declareRouteTool('get_skill', GET_SKILL_INPUTS);
 
+  // Both skill routes are also how prompts are read (`discovery`): a
+  // connection made as an agent configuration that names skills has them as
+  // prompts even when its `platformTools` does not offer these two tools.
   router.post(
     '/agent/tools/list_skills',
     toolAuth,
     toolHandler(async (args, ctx: ToolContext) => {
-      const skills = await skillService.listSkills(ctx.user.email, { branch: branchArg(args) });
+      const within = ctx.connectionScope?.skillFilter();
+      const skills = await skillService.listSkills(ctx.user.email, {
+        branch: branchArg(args),
+        ...(within ? { within } : {}),
+      });
       // Judged on each skill's SKILL.md, by the default branch's rules — a
       // skill only on a draft is judged where it would land. Each verdict goes
       // onto a COPY: the summaries may be the catalog shared across users.
       const verdicts = await verdictsFor(ctx, skills.map(skillMdOf));
       return { skills: skills.map((s) => ({ ...s, canWrite: verdicts.get(skillMdOf(s)) === true })) };
-    }),
+    }, { discovery: true }),
   );
 
   router.post(
@@ -174,7 +185,12 @@ export function registerSkillsTools(
           400,
         );
       }
-      const result = await skillService.getSkill(ctx.user.email, name, file, { version, branch });
+      const within = ctx.connectionScope?.skillFilter();
+      const result = await skillService.getSkill(ctx.user.email, name, file, {
+        version,
+        branch,
+        ...(within ? { within } : {}),
+      });
       if (!result.ok) return result;
       if (result.kind === 'file') {
         const verdicts = await verdictsFor(ctx, [result.file.path]);
@@ -193,7 +209,7 @@ export function registerSkillsTools(
       };
       if (!allowedTools) return { ...result, skill };
       return { ...result, skill, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
-    }),
+    }, { discovery: true }),
   );
 }
 
@@ -223,8 +239,13 @@ function branchArg(args: Record<string, unknown>): string | undefined {
  * the tool's fixed text leaves under {@link TOOL_DESCRIPTION_CAP} once the
  * guide-first sentence the registry puts in front is counted.
  */
-async function availableSkillsLine(skillService: ISkillService, userEmail: string | undefined, budget: number): Promise<string> {
-  const skills = await skillService.listSkills(userEmail);
+async function availableSkillsLine(
+  skillService: ISkillService,
+  userEmail: string | undefined,
+  budget: number,
+  within?: SkillScope,
+): Promise<string> {
+  const skills = await skillService.listSkills(userEmail, within ? { within } : {});
   if (skills.length === 0) return 'No skills are currently available.';
   const names = skills.map((s) => `\`${s.name}\``);
   const rest = (shown: number): string =>
@@ -276,12 +297,17 @@ const LIST_SKILLS_DESCRIPTION =
   'Each skill carries `canWrite`: whether you may change its SKILL.md directly on the default branch. ' +
   `${CAN_WRITE_CLAUSE} `;
 
-async function buildListSkillsDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
+async function buildListSkillsDef(skillService: ISkillService, userEmail?: string, within?: SkillScope): Promise<UtcpTool> {
   return toolDef({
     name: 'list_skills',
     description:
       LIST_SKILLS_DESCRIPTION +
-      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('list_skills', LIST_SKILLS_INPUTS, LIST_SKILLS_DESCRIPTION))),
+      (await availableSkillsLine(
+        skillService,
+        userEmail,
+        skillsLineBudget('list_skills', LIST_SKILLS_INPUTS, LIST_SKILLS_DESCRIPTION),
+        within,
+      )),
     path: '/api/agent/tools/list_skills',
     inputs: LIST_SKILLS_INPUTS,
     outputs: {
@@ -334,12 +360,17 @@ const GET_SKILL_DESCRIPTION =
   'The skill (or `file`) carries `canWrite`: whether you may change all of it directly on the default branch. ' +
   `${CAN_WRITE_CLAUSE} `;
 
-async function buildGetSkillDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
+async function buildGetSkillDef(skillService: ISkillService, userEmail?: string, within?: SkillScope): Promise<UtcpTool> {
   return toolDef({
     name: 'get_skill',
     description:
       GET_SKILL_DESCRIPTION +
-      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('get_skill', GET_SKILL_INPUTS, GET_SKILL_DESCRIPTION))),
+      (await availableSkillsLine(
+        skillService,
+        userEmail,
+        skillsLineBudget('get_skill', GET_SKILL_INPUTS, GET_SKILL_DESCRIPTION),
+        within,
+      )),
     path: '/api/agent/tools/get_skill',
     inputs: GET_SKILL_INPUTS,
     outputs: {

package/src/modules/tool-auth/__tests__/external-api-key.service.test.ts

@@ -150,6 +150,7 @@ describe('ExternalApiKeyService', () => {
         revokedAt: null,
         revokedBy: null,
         deletedAt: null,
+        agentPath: null,
       });
     });
 
@@ -370,6 +371,7 @@ describe('ExternalApiKeyService', () => {
         revokedAt: null,
         revokedBy: null,
         deletedAt: null,
+        agentPath: null,
       });
       expect(summaries[1].revokedAt).toBe(rows[1].revokedAt!.getTime());
       // sanity-check that ordering was requested (we can't introspect the
@@ -401,6 +403,7 @@ describe('ExternalApiKeyService', () => {
           revokedAt: null,
           revokedBy: null,
           deletedAt: null,
+          agentPath: null,
           user: { id: 'u-alice', email: 'alice@example.com', name: 'Alice' },
         },
         {
@@ -412,6 +415,7 @@ describe('ExternalApiKeyService', () => {
           revokedAt: bobKey.revokedAt!.getTime(),
           revokedBy: null,
           deletedAt: null,
+          agentPath: null,
           user: { id: 'u-bob', email: 'bob@example.com', name: 'Bob' },
         },
       ]);

package/src/modules/tool-auth/external-api-key.interface.ts

@@ -43,6 +43,11 @@ export interface ExternalApiKeySummary {
    * its row stays so the Audit log's events keep their principal.
    */
   deletedAt: number | null;
+  /**
+   * The agent configuration the key connects as (a repo-relative knowledge-base
+   * path), or null for Everything — chosen when the key was minted.
+   */
+  agentPath: string | null;
 }
 
 /** Who revoked a key: its owner, or an admin acting across the deployment. */
@@ -97,6 +102,11 @@ export interface KeyKindSpec {
  */
 export interface MintOptions {
   kind?: string;
+  /**
+   * The agent configuration the key connects as, already checked to be one the
+   * owner may choose (`IAgentScopeResolver.choosable`). Absent: Everything.
+   */
+  agentPath?: string;
 }
 
 /**
@@ -138,7 +148,7 @@ export interface IExternalApiKeyService {
    */
   verifyAndLoadToken(
     plaintext: string,
-  ): Promise<{ tokenId: string; user: AuthUser } | null>;
+  ): Promise<{ tokenId: string; user: AuthUser; agentPath?: string | null } | null>;
 
   /**
    * For a key {@link verifyAndLoadToken} refused: whether it is a live key

package/src/modules/tool-auth/external-api-key.service.ts

@@ -89,7 +89,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
     const [row] = await this.db
       .insert(externalApiKeys)
-      .values({ userId, tokenHash, label: trimmed, kind })
+      .values({ userId, tokenHash, label: trimmed, kind, ...(options.agentPath ? { agentPath: options.agentPath } : {}) })
       .returning();
 
     return {
@@ -118,7 +118,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
   async verifyAndLoadToken(
     plaintext: string,
-  ): Promise<{ tokenId: string; user: AuthUser } | null> {
+  ): Promise<{ tokenId: string; user: AuthUser; agentPath: string | null } | null> {
     if (!this.looksLikeExternalApiKey(plaintext)) {
       return null;
     }
@@ -135,6 +135,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
         tokenId: externalApiKeys.id,
         label: externalApiKeys.label,
         lastUsedAt: externalApiKeys.lastUsedAt,
+        agentPath: externalApiKeys.agentPath,
         userId: users.id,
         email: users.email,
         name: users.name,
@@ -176,6 +177,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
     return {
       tokenId: row.tokenId,
+      agentPath: row.agentPath,
       user: {
         id: row.userId,
         email: row.email,
@@ -353,5 +355,6 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
     revokedBy: (row.revokedBy as RevokedBy | null) ?? null,
     deletedAt: row.deletedAt ? row.deletedAt.getTime() : null,
+    agentPath: row.agentPath ?? null,
   };
 }

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

@@ -10,5 +10,5 @@ import './external-api-key.interface.js';
 export type { InternalTokenService } from './internal-token.service.js';
 export type { ILlmUsageMeter } from './llm-usage-meter.js';
 export { createTokenVerifier, requireExternalSource, requireInternalSource } from './tool-auth.middleware.js';
-export type { ToolAuth } from './tool-auth.middleware.js';
+export type { ConnectionChoices, ToolAuth } from './tool-auth.middleware.js';
 import './tool-auth.middleware.js';