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

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

@@ -10,6 +10,7 @@ import {
   scopesCovered,
   missingScopes,
   configuredAs,
+  type DeclaredOAuthProvider,
   type ISecretsVaultService,
 } from './secrets-vault.contract.js';
 import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/index.js';
@@ -17,10 +18,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). */
@@ -44,6 +54,38 @@ function redirectUriFor(publicBackendUrl: string): string {
   return `${publicBackendUrl}/api/secrets/oauth/callback`;
 }
 
+/**
+ * What of a declared sign-in is its provider configuration — ONE reading, for
+ * the client-secret save (which stores it as a record) and the sign-in start
+ * (which runs from it). `null` while the declaration has no endpoints: it named
+ * only its client id and the server's metadata could not complete it.
+ */
+function declaredProvider(variable: ToolVariable): DeclaredOAuthProvider | null {
+  const oauth = variable.oauth;
+  if (!oauth?.authorizationUrl || !oauth.tokenUrl) return null;
+  return {
+    authorizationUrl: oauth.authorizationUrl,
+    tokenUrl: oauth.tokenUrl,
+    clientId: oauth.clientId,
+    scopes: oauth.scopes,
+    // Static authorize params (e.g. Google's `access_type=offline`) so the
+    // provider returns a refresh token.
+    authParams: oauth.authParams,
+    // PKCE unless the declaration opted out; the resource indicator when the
+    // server (or the declaration) names one.
+    pkce: oauth.pkce !== false,
+    resource: oauth.resource,
+  };
+}
+
+/** Why a declared sign-in has no endpoints — the discovery's own reason when it gave one. */
+function endpointsUnknown(manual: ToolManualSummary): string {
+  const why = manual.setup?.reason;
+  return why
+    ? `The sign-in endpoints for this server aren't known yet: ${why}.`
+    : "The sign-in endpoints for this server aren't known yet — declare `authorizationUrl` and `tokenUrl` on the sign-in variable.";
+}
+
 /**
  * Is this a SAME-ORIGIN path we're willing to bounce the browser back to after a
  * sign-in? The callback builds `${publicFrontendUrl}${dest}#…`, so anything that
@@ -267,12 +309,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 +422,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 }));
@@ -441,8 +494,8 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
 
   // Set the confidential client secret for a tool's OAuth-backed variable — the
   // ONLY place the secret is provided. Requires WRITE on the `.tool`. The provider
-  // config comes from the variable's own `oauth` declaration (stored WITH the
-  // secret so a later `.tool` edit can't redirect it).
+  // config of the variable's own `oauth` declaration is stored with the secret as
+  // a record of the save; a sign-in start reads the declaration afresh.
   router.put('/secrets/tools/:slug/vars/:var/oauth/admin', async (req, res) => {
     const userId = req.userId;
     const email = req.userEmail;
@@ -456,38 +509,17 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       if (!(await accessControl.canWrite(defaultWs(), email, found.manual.path))) {
         return void res.status(403).json({ error: 'You need write access to this tool to set its client secret.' });
       }
-      const { authorizationUrl, tokenUrl } = found.variable.oauth;
       // A declaration that names only its client id is completed from the
-      // server's OAuth metadata at scan time. When that didn't happen, pinning
-      // the secret to a provider with no endpoints would leave every sign-in
-      // failing later with a far less specific error than the catalog's own.
-      if (!authorizationUrl || !tokenUrl) {
-        const why = found.manual.setup?.reason;
-        return void res.status(422).json({
-          error: why
-            ? `The sign-in endpoints for this server aren't known yet: ${why}.`
-            : "The sign-in endpoints for this server aren't known yet — declare `authorizationUrl` and `tokenUrl` on the sign-in variable.",
-        });
-      }
+      // server's OAuth metadata. When that didn't happen, storing the secret
+      // with a provider that has no endpoints would leave every sign-in failing
+      // later with a far less specific error than the catalog's own.
+      const provider = declaredProvider(found.variable);
+      if (!provider) return void res.status(422).json({ error: endpointsUnknown(found.manual) });
       const clientSecret = (req.body ?? {}).clientSecret;
       await secretsVault.putSharedOAuthClientSecret({
         key: varKey(found.manual.name, found.variable.name),
         clientSecret,
-        provider: {
-          authorizationUrl,
-          tokenUrl,
-          clientId: found.variable.oauth.clientId,
-          scopes: found.variable.oauth.scopes,
-          // Static authorize params (e.g. Google's `access_type=offline`) so the
-          // provider returns a refresh token — stored with the secret so a later
-          // `.tool` edit can't redirect the flow.
-          authParams: found.variable.oauth.authParams,
-          // PKCE unless the declaration opted out; the resource indicator when
-          // the server (or the declaration) names one. Both pinned here for the
-          // same reason as the rest: the flow runs from the stored row.
-          pkce: found.variable.oauth.pkce !== false,
-          resource: found.variable.oauth.resource,
-        },
+        provider,
       });
       res.status(201).json({ ok: true });
     } catch (err) {
@@ -505,12 +537,37 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     const email = req.userEmail;
     if (!userId || !email) return void res.status(401).json({ error: 'Not authenticated' });
     try {
-      const found = await findManualVar(email, req.params.slug, req.params.var);
-      if (!found) return void res.status(404).json({ error: 'Tool or variable not found' });
-      if (!found.variable.oauth) {
-        return void res.status(422).json({ error: 'This variable is not an OAuth sign-in.' });
+      // Two sources, one per kind of sign-in. A DECLARED one follows its tool
+      // file as it reads now — never the catalog's scan, which can be a refresh
+      // behind the file, and never the copy the client-secret save stored. A
+      // client the platform registered itself (oauth-auto) is described by no
+      // file: the catalog's discovery surfaced it, and its stored row is the
+      // only description of it there is.
+      const [live, catalog] = await Promise.all([
+        toolManualService.liveDeclaration(email, req.params.slug, req.params.var),
+        findManualVar(email, req.params.slug, req.params.var),
+      ]);
+      // The file is there but its declaration is refused as it reads now (an
+      // http:// or private endpoint, say): the parser's reason is the answer,
+      // and neither a catalog still holding the earlier version nor the stored
+      // row stands in for it. Nothing is sent anywhere.
+      if (live?.refused) return void res.status(422).json({ error: live.refused });
+      const manual = live?.manual ?? catalog?.manual;
+      if (!manual || (!live?.variable && !catalog)) {
+        return void res.status(404).json({ error: 'Tool or variable not found' });
       }
-      const key = varKey(found.manual.name, found.variable.name);
+      const key = varKey(manual.name, req.params.var);
+      const declared = live?.variable?.oauth ? live.variable : null;
+      const registered =
+        !declared && catalog?.manual.setup?.kind === 'oauth-auto' && catalog.variable.oauth ? catalog.variable : null;
+      const signIn = declared ?? registered;
+      // No sign-in in the file and none the platform registered: whatever the
+      // shared row still holds is not used.
+      if (!signIn?.oauth) {
+        throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
+      }
+      const provider = declared ? declaredProvider(declared) : undefined;
+      if (provider === null) return void res.status(422).json({ error: endpointsUnknown(manual) });
       // Provision the caller's oauth row (from the owner-set secret) FIRST — its id
       // is what the un-authed callback keys on. Pass an empty state placeholder; we
       // sign the real state below with the returned id and swap it into the URL, so
@@ -520,10 +577,10 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
         key,
         redirectUri: redirectUriFor(deps.publicBackendUrl),
         state: '',
-        // Request the permissions the tool file declares RIGHT NOW (not the frozen
-        // copy on the owner-set row), so adding a scope to the `.tool` takes effect
-        // on the next sign-in. The secret/clientId/addresses stay owner-pinned.
-        scopes: found.variable.oauth.scopes,
+        // Request the permissions the tool file declares RIGHT NOW, so adding a
+        // scope takes effect on the next sign-in.
+        scopes: signIn.oauth.scopes,
+        provider,
       });
       // The return path is signed INTO the state (HMAC-SHA256) rather than kept
       // in a query param or a cookie: the callback arrives un-authenticated from
@@ -637,7 +694,22 @@ export function createSecretsVaultPublicRoutes(deps: SecretsVaultRoutesDeps): ex
       back(`authorized=${encodeURIComponent(state.i)}`, dest);
     } catch (err) {
       log.error('oauth callback failed:', { err });
-      back(`error=${encodeURIComponent('Authorization failed. Check the provider configuration and try again.')}`, dest);
+      // A provider's REFUSAL (the vault's error carrying the provider's HTTP
+      // status) names the provider's error code and Hexis's own sentence for
+      // it — the one thing the person on the Connect page (or the agent they
+      // paste it to) can act on: a client the provider does not accept, a
+      // refused authorization code. Nothing of the provider's text is in it.
+      // Every other failure stays the generic line: a transport error quotes
+      // what fetch said, which is not a provider's word.
+      const refusal = err instanceof SecretOAuthError && err.providerStatus !== undefined ? err.message : null;
+      back(
+        `error=${encodeURIComponent(
+          refusal
+            ? `Authorization failed. ${refusal}`
+            : 'Authorization failed. Check the provider configuration and try again.',
+        )}`,
+        dest,
+      );
     }
   });
 

package/src/modules/settings/oidc-check.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from 'node:crypto';
+import { isStandardTokenErrorCode } from '../../shared/oauth-token-error.js';
 
 /** The single sign-on configuration a deployment would sign people in with. */
 export interface OidcConfiguration {
@@ -55,21 +56,6 @@ const REQUEST_TIMEOUT_MS = 10_000;
  */
 const CODE_REJECTIONS: readonly string[] = ['invalid_grant'];
 
-/**
- * The other error codes RFC 6749 §5.2 (and OIDC Core §3.1.2.6) define — the
- * only ones echoed back in an "unverified" message. Anything else in `error`
- * is text of the provider's choosing, and could be the secret reflected back.
- */
-const ECHOED_ERRORS: readonly string[] = [
-  'invalid_request',
-  'unauthorized_client',
-  'unsupported_grant_type',
-  'invalid_scope',
-  'access_denied',
-  'server_error',
-  'temporarily_unavailable',
-];
-
 /** The issuer as the provider appends `/.well-known/...` to it: no trailing slash. */
 export function normalizeIssuerUrl(issuerUrl: string): string {
   return issuerUrl.trim().replace(/\/+$/, '');
@@ -219,9 +205,10 @@ export async function checkOidcConfiguration(
     };
   }
   if (CODE_REJECTIONS.includes(errorCode)) return { outcome: 'verified' };
-  // Only a standard error code is echoed — anything else could be text of the
-  // provider's choosing, the secret included.
-  const code = ECHOED_ERRORS.includes(errorCode) ? ` (${errorCode})` : ` (HTTP ${status})`;
+  // Only a standard error code is echoed (the one list the vault reads a
+  // refusal by too) — anything else could be text of the provider's choosing,
+  // the secret included.
+  const code = isStandardTokenErrorCode(errorCode) ? ` (${errorCode})` : ` (HTTP ${status})`;
   return {
     outcome: 'unverified',
     error: `The application ID and secret could not be verified — the provider gave an answer that does not say whether they are right${code}.`,

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';
 
@@ -33,7 +33,7 @@ const LIST_SKILLS_INPUTS = {
 const GET_SKILL_INPUTS = {
   type: 'object' as const,
   properties: {
-    name: { type: 'string' as const, minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
+    name: { type: 'string' as const, minLength: 1, description: 'Skill name, as `list_skills` gives it (its `id`, else its `name`, else its folder name; e.g. `rfi`).' },
     file: {
       type: 'string' as const,
       description:
@@ -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';