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

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

@@ -26,3 +26,5 @@ export {
   BEVEL_SECRETS_LOADER_TYPE,
   DEFAULT_SECRETS_SCOPE,
 } from './secrets-variable-loader.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { scopesCovered } from './secrets-vault.contract.js';

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

@@ -12,15 +12,24 @@ import {
   configuredAs,
   type ISecretsVaultService,
 } from './secrets-vault.contract.js';
-import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/tool-manuals.contract.js';
-import type { IConnectionProbeService } from '../connection-probe/connection-probe.contract.js';
+import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/index.js';
+import type { IConnectionProbeService } from '../connection-probe/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
+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/settings/__tests__/deployment-settings.service.test.ts

@@ -8,8 +8,11 @@ import {
   CORE_SETTINGS,
   LEGACY_LAYOUT_ENV_VARS,
   retireMergedBranchesOn,
+  parseToolReadOnlyOverrides,
 } from '../deployment-settings.service.js';
 import type { Database } from '../../database/connection.js';
+import { ToolReadOnlyHints, ToolRegistry } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
 
 const ENC_KEY = randomBytes(32).toString('base64');
 
@@ -22,7 +25,16 @@ const ENC_KEY = randomBytes(32).toString('base64');
 function makeDb() {
   const rows: { key: string; value: string; encrypted: boolean }[] = [];
   const db = {
-    select: () => ({ from: () => Promise.resolve(rows.map((r) => ({ ...r }))) }),
+    // `select … from` is every row; `… where key = ?` (a `reload`) is that key's.
+    select: () => ({
+      from: () =>
+        Object.assign(Promise.resolve(rows.map((r) => ({ ...r }))), {
+          where: (predicate: unknown) => {
+            const [key] = boundParams(predicate);
+            return Promise.resolve(rows.filter((r) => r.key === key).map((r) => ({ ...r })));
+          },
+        }),
+    }),
     insert: () => ({
       values: (v: { key: string; value: string; encrypted: boolean }) => ({
         onConflictDoUpdate: () => {
@@ -677,3 +689,78 @@ describe('DeploymentSettingsService — recordIfAbsent', () => {
     expect(settings.resolve('starterPackClaim')).toBe('');
   });
 });
+
+describe('DeploymentSettingsService — the read-only overrides', () => {
+  /** A registry with one reader and one writer, as the Tools page would show them. */
+  function registry(): ToolRegistry {
+    const r = new ToolRegistry();
+    const inputs = { type: 'object', properties: {} } as const;
+    r.registerExternalTool(toolDef({ name: 'read_file', description: 'r', path: '/api/agent/tools/read_file', inputs }));
+    r.registerExternalTool(
+      toolDef({ name: 'write_file', description: 'w', path: '/api/agent/tools/write_file', inputs, tags: ['write'] }),
+    );
+    return r;
+  }
+
+  it('survives a restart: a new process over the same table reads the override back', async () => {
+    const { db, rows } = makeDb();
+    const before = new DeploymentSettingsService(db, ENC_KEY);
+    await before.load();
+    await new ToolReadOnlyHints(registry(), before).set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    expect(rows.find((r) => r.key === 'toolReadOnlyOverrides')?.value).toBe('{"write_file":true}');
+
+    const after = new DeploymentSettingsService(db, ENC_KEY);
+    await after.load();
+    const hints = new ToolReadOnlyHints(registry(), after);
+    expect((await hints.describe()).find((e) => e.name === 'write_file')).toMatchObject({ override: true, readOnly: true });
+
+    // And the reset removes the row, every tool back on its built-in value.
+    await hints.set('write_file', null, '00000000-0000-4000-8000-00000000000a');
+    expect(rows.find((r) => r.key === 'toolReadOnlyOverrides')).toBeUndefined();
+  });
+
+  it('is read per use, so a change written by another replica is in the next answer', async () => {
+    const { db } = makeDb();
+    const one = new DeploymentSettingsService(db, ENC_KEY);
+    const two = new DeploymentSettingsService(db, ENC_KEY);
+    await one.load();
+    await two.load();
+    await new ToolReadOnlyHints(registry(), one).set('read_file', false, null);
+    expect(await new ToolReadOnlyHints(registry(), two).overrides()).toEqual({ read_file: false });
+  });
+
+  it('is not a field of the setup screen: a save naming it is refused, and the screen is not told of it', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.load();
+    await expect(settings.save({ toolReadOnlyOverrides: '{"write_file":true}' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    expect(rows).toEqual([]);
+    expect(settings.describe().some((s) => s.key === 'toolReadOnlyOverrides')).toBe(false);
+  });
+
+  it('refuses a stored value that is not a map of tool names to booleans', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.load();
+    await expect(settings.recordIfAbsent('toolReadOnlyOverrides', '{"write_file":"yes"}', null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+  });
+});
+
+describe('the read-only overrides setting holds only a map of tool names to booleans', () => {
+  it('accepts a map, and blank as no override', () => {
+    expect(parseToolReadOnlyOverrides('{"read_file":false,"call_tool_chain":true}')).toEqual({
+      read_file: false,
+      call_tool_chain: true,
+    });
+    expect(parseToolReadOnlyOverrides('')).toEqual({});
+    expect(Object.hasOwn(parseToolReadOnlyOverrides('{"__proto__":true}')!, '__proto__')).toBe(true);
+  });
+
+  it.each(['[]', 'true', '{"read_file":"false"}', '{"bad name":true}', 'not json'])('refuses %s', (raw) => {
+    expect(parseToolReadOnlyOverrides(raw)).toBeNull();
+  });
+});

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

@@ -6,7 +6,7 @@ import { validateHttpsRemote } from './deployment-settings.service.js';
 import { classifyGitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
-import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../workflow/index.js';
 
 /** The repository connection a deployment reads and writes its knowledge base with. */
 export interface RepositoryConnection {

package/src/modules/settings/deployment-settings.service.ts

@@ -2,8 +2,8 @@ import { and, eq, inArray } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('settings');
-import type { Database } from '../database/connection.js';
-import { deploymentSettings } from '../database/core-schema.js';
+import type { Database } from '../database/index.js';
+import { deploymentSettings } from '../database/index.js';
 import {
   DEFAULT_KB_LAYOUT,
   type KbLayout,
@@ -13,8 +13,8 @@ import {
 } from '@bevel-software/platform-shared';
 import { createHmac } from 'node:crypto';
 import { TokenCrypto } from '../../shared/token-crypto.js';
-import { assertKbDirNameFree, hasControlCharacter } from '../kb-fs/repo-path.js';
-import { parseRetentionWindow } from '../audit/audit.contract.js';
+import { assertKbDirNameFree, hasControlCharacter } from '../kb-fs/index.js';
+import { parseRetentionWindow } from '../audit/index.js';
 import { normalizeIssuerUrl } from './oidc-check.js';
 import { GIT_MODES, isGitMode } from './repository-source.js';
 
@@ -119,6 +119,29 @@ export function retireMergedBranchesOn(raw: string): boolean {
   return !/^(false|0|off|no)$/i.test(raw.trim());
 }
 
+/**
+ * The `toolReadOnlyOverrides` setting read as a map, or null when it is not
+ * one: a JSON object whose keys are tool names (MCP's name grammar) and whose
+ * values are booleans. Blank is no override at all.
+ */
+export function parseToolReadOnlyOverrides(raw: string): Record<string, boolean> | null {
+  if (!raw.trim()) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const entries = Object.entries(parsed as Record<string, unknown>);
+  for (const [name, value] of entries) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(name) || typeof value !== 'boolean') return null;
+  }
+  // Built with `fromEntries`, which defines own properties: assigning into a
+  // plain object would send a valid name like `__proto__` to its prototype.
+  return Object.fromEntries(entries) as Record<string, boolean>;
+}
+
 export const CORE_SETTINGS: SettingDef[] = [
   {
     /**
@@ -400,6 +423,23 @@ export const CORE_SETTINGS: SettingDef[] = [
       parseRetentionWindow(v) === null ? 'Enter a whole number of days, or 0 to keep events forever.' : null,
   },
 
+  {
+    /**
+     * The read-only hints an admin set on the Tools page, overriding a
+     * platform tool's or a code-mode meta-tool's built-in one: a JSON map from
+     * tool name to `true`/`false`. Written by the Tools page's admin route
+     * alone (see `modules/tool-registry/read-only-hints.ts`), which also judges
+     * the NAMES against the catalog; here only the shape is. Internal: not a
+     * field of the setup screen. A blank clears it, which is every tool back
+     * on its built-in value.
+     */
+    key: 'toolReadOnlyOverrides',
+    section: 'knowledge-base',
+    internal: true,
+    blankMeansDefault: true,
+    validate: (v) => (parseToolReadOnlyOverrides(v) === null ? 'A map from tool name to true or false.' : null),
+  },
+
   {
     /**
      * Which starter pack the first admin chose for a new knowledge base — a

package/src/modules/settings/git-root-folders.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { IGitRunner } from '../../shared/git.contract.js';
 import { printable } from '../../shared/printable.js';
 import { logger } from '../../shared/logging.js';
-import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../workflow/index.js';
 import { probeCredentialArgs, probeGitEnv } from './connection-check.js';
 
 const log = logger('setup');

package/src/modules/settings/index.ts

@@ -0,0 +1,12 @@
+/**
+ * What the settings module offers the other modules: the deployment settings
+ * service as a contract for a route that reads or writes a setting, the
+ * parsers of the settings whose stored text another module interprets (the
+ * tool read-only overrides), and the shapes of the repository source a git
+ * integration configures itself from. The service is wired by the
+ * composition root.
+ */
+export type { DeploymentSettingsService, ResolvedSetting, SettingSource } from './deployment-settings.service.js';
+export { parseToolReadOnlyOverrides } from './deployment-settings.service.js';
+export { normalizeIssuerUrl } from './oidc-check.js';
+export type { GitHubAppRepository, SettingReader } from './repository-source.js';

package/src/modules/settings/setup.routes.ts

@@ -1,10 +1,11 @@
 import express from 'express';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IAdminAccessService } from '../admin/index.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('setup');
+import type {
+  DeploymentSettingsService} from './deployment-settings.service.js';
 import {
-  DeploymentSettingsService,
   SettingsValidationError,
   validateHttpsRemote,
   type OidcCredentials,
@@ -31,10 +32,10 @@ import type { KbContext } from '../../shared/kb-context.js';
 import { failureOf, type GitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { listRootFolders, pickListingBranch } from './git-root-folders.js';
-import { sameRepository } from '../kb-fs/remote-url.js';
+import { sameRepository } from '../kb-fs/index.js';
 import { MANAGED_DEFAULT_BRANCH } from './managed-repository.js';
 import { GIT_MODES, type GitHubAppRepository, type RepositorySource } from './repository-source.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 /**
  * What setup needs of the ways a deployment can be given its repository:

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -14,7 +14,7 @@ import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
-import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
+import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import { registerSkillsTools } from '../skills.tools.js';
@@ -111,7 +111,7 @@ async function start(): Promise<string> {
   const router = express.Router();
   registerWorkspaceTools(
     registry, router, fakeAuth, toolHandler,
-    new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+    new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), new WorkerDocumentExtractor()), allowAll, testKbContext({ kbDirName: KB_DIR }),
     { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
     new RoutineWritePolicyService(),
     {} as never,

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -11,6 +11,7 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { JoinRequestsService } from '../../plugins/join-requests.service.js';
 import type { ISkillService } from '../skills.contract.js';
 import { createSkillAccessRequestRoutes } from '../skill-access-requests.routes.js';
+import { AccessRequestsService } from '../../access/access-requests.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
@@ -49,15 +50,17 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
 
   const app = express();
   app.use(express.json());
+  const joinRequests = { list: vi.fn(), reconcile: vi.fn() } as unknown as JoinRequestsService;
+  const kb = testKbContext({ kbDirName: KB });
   app.use(
     '/api',
     createSkillAccessRequestRoutes({
       skillService,
       accessControl,
       workflow,
-      workspaceService,
-      joinRequests: { list: vi.fn(), reconcile: vi.fn() } as unknown as JoinRequestsService,
-      kb: testKbContext({ kbDirName: KB }),
+      requests: new AccessRequestsService({ workflow, workspaceService, lifecycle: joinRequests, kb }),
+      joinRequests,
+      kb,
       resolveUser: async () => MIA,
     }),
   );

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/allowed-tools-check.ts

@@ -1,11 +1,7 @@
 import { logger } from '../../shared/logging.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IToolRegistry } from '../tool-registry/tool.contract.js';
-import {
-  EXTERNAL_KB_MANUAL_NAME,
-  MAX_CAPABILITIES,
-  type IToolManualService,
-} from '../tool-manuals/tool-manuals.contract.js';
+import type { IToolRegistry } from '../tool-registry/index.js';
+import { EXTERNAL_KB_MANUAL_NAME, type IToolManualService, MAX_CAPABILITIES } from '../tool-manuals/index.js';
 import { parseSkillFrontmatter } from './skills.service.js';
 
 const log = logger('skills');

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,5 +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/pending-skills.service.ts

@@ -1,12 +1,11 @@
-import type { KbLayout } from '@bevel-software/platform-shared';
-import { type WorkspaceService } from '../workspace/workspace.service.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { KbLayout, IWorkflowService } from '@bevel-software/platform-shared';
+import { type WorkspaceService } from '../workspace/index.js';
+import type { IAccessControl } from '../access/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { resolveDeclaredId } from '../../shared/frontmatter-id.js';
 import { visibleProposedFiles } from '../../shared/pending-proposals.js';
 import { isSafeSkillName, parseSkillFrontmatter } from './skills.service.js';
 import type { IPendingSkillService, ISkillService, PendingSkill } from './skills.contract.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
 
 const SKILL_DOC = 'SKILL.md';
 

package/src/modules/skills/skill-access-requests.routes.ts

@@ -2,16 +2,14 @@ import express from 'express';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('skills');
-import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import '../auth/index.js'; // Express Request.userId / userEmail augmentation
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { folderTarget } from '../access/access-requests.contract.js';
-import { AccessRequestsService } from '../access/access-requests.service.js';
+import type { IAccessControl, IAccessRequests } from '../access/index.js';
+import { folderTarget } from '../access/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
-import type { JoinRequestsService } from '../plugins/join-requests.service.js';
+import type { JoinRequestsService } from '../plugins/index.js';
 import type { ISkillService } from './skills.contract.js';
 
 /**
@@ -37,24 +35,19 @@ export function createSkillAccessRequestRoutes(deps: {
   skillService: ISkillService;
   accessControl: IAccessControl;
   workflow: IWorkflowService;
-  workspaceService: WorkspaceService;
+  /** Opens an access request — the same opener the Manage access dialog uses, wired by the composition root. */
+  requests: IAccessRequests;
   joinRequests: JoinRequestsService;
   kb: KbContext;
   resolveUser: (req: express.Request) => Promise<AuthUser | null>;
 }): express.Router {
-  const { skillService, accessControl, workflow, workspaceService, joinRequests, kb, resolveUser } = deps;
+  const { skillService, accessControl, workflow, requests, joinRequests, kb, resolveUser } = deps;
   const router = express.Router();
   const wsId = () => kb.defaultWorkspaceId();
   const rulesOf = (folder: string) => `${folder}/access.md`;
-  // The same opener the Manage access dialog uses, pointed at a skill's
-  // folder. Keyed on that folder's PATH, which is what makes this button and
-  // a Can edit request on the same folder one request rather than two.
-  const requests = new AccessRequestsService({
-    workflow,
-    workspaceService,
-    lifecycle: joinRequests,
-    kb,
-  });
+  // `requests` is pointed at a skill's folder below. Keyed on that folder's
+  // PATH, which is what makes this button and a Can edit request on the same
+  // folder one request rather than two.
 
   /** The skill the caller may read, by name — or null after answering 404. */
   async function readableSkill(

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

@@ -1,5 +1,5 @@
 import express from 'express';
-import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import '../auth/index.js'; // Express Request.userId / userEmail augmentation
 import type { KbContext } from '../../shared/kb-context.js';
 import type { IPendingSkillService, ISkillService, PluginMembership } from './skills.contract.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';

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

@@ -5,9 +5,9 @@ const log = logger('skills');
 import fs from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { parseDocument } from 'yaml';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { extractFrontmatter, resolveDeclaredId, dedupeById } from '../../shared/frontmatter-id.js';
 import type { IgnoreRules, ITreeWalker } from '../../shared/fs.contract.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
@@ -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