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

package/src/modules/plugins/plugins.contract.ts

@@ -33,7 +33,7 @@
  * change requests; only the UI dresses them up.
  */
 
-export type { PluginMembership } from '../skills/skills.contract.js';
+export type { PluginMembership } from '../skills/index.js';
 
 /** Access-rule principals as the resolver hands them back. */
 export interface ResolvedPrincipals {

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

@@ -2,7 +2,7 @@ import express from 'express';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
-import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import '../auth/index.js'; // Express Request.userId / userEmail augmentation
 import {
   joinBranchFor,
   type AuthUser,
@@ -10,17 +10,17 @@ import {
   type ChangeRequestState,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 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/route-argument-check.js';
+import { argumentsRefusal } from '../tool-helpers/index.js';
 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';
-import { folderTarget } from '../access/access-requests.contract.js';
+import { folderTarget } from '../access/index.js';
 import type { PluginJoinRequestJobs } from './join-request-jobs.service.js';
 import type { JoinRequestRecord } from './join-request-records.store.js';
 import type {

package/src/modules/plugins/plugins.service.ts

@@ -3,13 +3,13 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
 import path from 'node:path';
-import { isPrivateAccessMd } from '../access-model/access-grammar.js';
+import { isPrivateAccessMd } from '../access-model/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-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 { ISkillService } from '../skills/skills.contract.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import type { IAccessControl } from '../access/index.js';
+import type { ISkillService } from '../skills/index.js';
+import type { IToolManualService } from '../tool-manuals/index.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
 import type { PluginCatalogEntry, IPluginIndexService } from './plugins.contract.js';
 import type { PluginLinkIndex } from './plugin-links.js';

package/src/modules/plugins/plugins.tools.ts

@@ -1,7 +1,7 @@
 import { resolveKbLayout, type KbLayout } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
+import { toolDef } from '../tool-helpers/index.js';
 
 /**
  * The two plugin tools an agent has, both surfaces — DESCRIPTIONS of the
@@ -112,7 +112,7 @@ export function myPluginDef(layout: KbLayout): UtcpTool {
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: PROVISIONED_OUTPUT,
     // `write`: both make folders and commit — a read-scoped caller's manual
-    // must not advertise them (see `isWriteTool` in the manual routes).
+    // must not advertise them (see `declaresWrite` in `tool.contract.ts`).
     tags: ['plugins', 'skills', 'write'],
   });
 }
@@ -143,6 +143,6 @@ export const CREATE_PLUGIN: UtcpTool = toolDef({
   },
   outputs: PROVISIONED_OUTPUT,
   // `write`: both make folders and commit — a read-scoped caller's manual
-  // must not advertise them (see `isWriteTool` in the manual routes).
+  // must not advertise them (see `declaresWrite` in `tool.contract.ts`).
   tags: ['plugins', 'skills', 'write'],
 });

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

@@ -8,10 +8,10 @@ import {
   pluginOfPath,
   type KbLayout,
 } from '@bevel-software/platform-shared';
-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 type { ISkillService } from '../skills/skills.contract.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import type { ISkillService } from '../skills/index.js';
+import type { IToolManualService } from '../tool-manuals/index.js';
 import type { IPluginIndexService, PluginCatalogEntry } from './plugins.contract.js';
 
 /**

package/src/modules/secrets-vault/db-secrets-vault.service.ts

@@ -3,8 +3,8 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('vault');
 import { and, desc, eq, inArray, isNull, like, or } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
-import { secrets } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { secrets } from '../database/index.js';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import {

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,12 +12,12 @@ 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 '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface SecretsVaultRoutesDeps {
   secretsVault: ISecretsVaultService;

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

@@ -16,3 +16,5 @@ export type {
   GetSkillOptions,
   SkillHistorySource,
 } 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.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';

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

@@ -1,16 +1,12 @@
 import type { Router, RequestHandler } from 'express';
 import { callLine } from '@bevel-software/platform-mcp-core';
-import type { IToolRegistry, JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
-import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
-import { GUIDE_FIRST_SENTENCE } from '../tool-registry/guide-first.js';
-import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import { bodyEnvelope, declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { IToolRegistry, JsonSchema, UtcpTool } from '../tool-registry/index.js';
+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 { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';
-import { CAN_WRITE_CLAUSE, defaultBranchWriteVerdicts, type DefaultBranchWriteDeps } from '../tool-helpers/index.js';
 
 /**
  * The optional `branch` both skill tools declare. Optional on purpose, unlike

package/src/modules/tool-auth/connection-key-rejection.ts

@@ -1,5 +1,5 @@
 import type { Response } from 'express';
-import { ACCOUNT_DEACTIVATED_MESSAGE } from '../auth/account-admission.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE } from '../auth/index.js';
 
 /**
  * How every key-authenticated endpoint answers a bearer that LOOKS like a

package/src/modules/tool-auth/connection-keys-admin.routes.ts

@@ -2,10 +2,10 @@ import express from 'express';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('connection-keys');
-import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IAdminAccessService } from '../admin/index.js';
 import { TokenNotFoundError } from './external-api-key.errors.js';
 import type { IExternalApiKeyService } from './external-api-key.interface.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 /** Shape of the `api_tokens.id` column (any uuid version; case-insensitive). */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

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

@@ -4,8 +4,8 @@ import { logger } from '../../shared/logging.js';
 const log = logger('external-api-key');
 import { and, desc, eq, isNotNull, isNull, type SQL } from 'drizzle-orm';
 import type { AgentConnectedEvent, AuthUser } from '@bevel-software/platform-shared';
-import type { Database } from '../database/connection.js';
-import { externalApiKeys, users } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { externalApiKeys, users } from '../database/index.js';
 import {
   InvalidTokenLabelError,
   TokenNotFoundError,

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

@@ -0,0 +1,14 @@
+/**
+ * What the tool-auth module offers the other modules. A consumer outside the
+ * module imports from here, never from the files: they are the module's own
+ * layout and free to move. Export what another module needs; nothing more.
+ */
+export { rejectConnectionKey } from './connection-key-rejection.js';
+export { InvalidTokenLabelError, TokenNotFoundError, TokenStillActiveError } from './external-api-key.errors.js';
+export type { IExternalApiKeyService, KeyKindSpec, MintedExternalApiKey } from './external-api-key.interface.js';
+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';
+import './tool-auth.middleware.js';