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

package/src/modules/embed/embed.routes.ts

@@ -7,8 +7,8 @@ import {
   EmbedTokenError,
 } from './embed.errors.js';
 import { EmbedRefParseError } from './embed-link.js';
-import { rawExtensionOf, rawMimeFor } from '../workspace/file-readers/raw-mime.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import { rawExtensionOf, rawMimeFor } from '../workspace/index.js';
+import '../auth/index.js'; // Express Request augmentation
 
 /**
  * What `/api/embed/raw` answers as `Content-Type`, by extension — the types a

package/src/modules/embed/embed.service.ts

@@ -6,7 +6,7 @@ import { suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.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 { changeRequestLink, changeRequestLinkBase } from '../workflow/index.js';
 import type { FileReaderRegistry } from '../workspace/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';

package/src/modules/embed/embed.tools.ts

@@ -1,15 +1,12 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry } from '../tool-registry/tool.contract.js';
-import { ToolError } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import type { IToolRegistry } from '../tool-registry/index.js';
+import { ToolError, toolDef } from '../tool-helpers/index.js';
+import type { ToolHandlerFactory, ToolContext } from '../tool-helpers/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { ReadForTool } from '../workspace/workspace.tools.js';
+import type { ReadForTool } from '../workspace/index.js';
 import type { IEmbedService } from './embed.interface.js';
-import { requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
-import { SESSION_ID_INPUT, type ToolDescriptionNotes } from '../workspace/agent-access.gate.js';
-import { sessionIdInputOf } from '../workspace/workspace.tools.js';
+import { requireExternalSource } from '../tool-auth/index.js';
+import { SESSION_ID_INPUT, type ToolDescriptionNotes, sessionIdInputOf } from '../workspace/index.js';
 
 /** The tool name, in one place: the app manifest keys its view by it. */
 export const OPEN_PAGE_TOOL = 'open_page';

package/src/modules/github-app/github-app.connection.ts

@@ -1,5 +1,5 @@
 import { logger } from '../../shared/logging.js';
-import type { GitHubAppRepository, SettingReader } from '../settings/repository-source.js';
+import type { GitHubAppRepository, SettingReader } from '../settings/index.js';
 import {
   GitHubAppClient,
   type GitHubAppCredentials,

package/src/modules/github-app/github-app.routes.ts

@@ -1,11 +1,11 @@
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 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';
-import type { DeploymentSettingsService } from '../settings/deployment-settings.service.js';
+import type { DeploymentSettingsService } from '../settings/index.js';
 import { GitHubAppClient, GitHubAppError } from './github-app.client.js';
 import { repositoriesAsSetting, type GitHubAppConnection } from './github-app.connection.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 const log = logger('github-app');
 

package/src/modules/kb-fs/index.ts

@@ -7,3 +7,14 @@ export type { WriteValidator } from './locking-filesystem.js';
 export { WorkspaceMutex, WorkspaceIdMutex } from './mutex.js';
 export { readRefSha, readRevSha, type RefFileAnswer } from './ref-files.js';
 export { gitDirOf, readGitfile } from './git-dir.js';
+export { normalizeWorkspacePath } from './repo-path.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { BevelIgnoreStack } from './bevel-ignore.js';
+export { assertValidBranchName, assertValidRelativePath, isBranchAuthoredBy, isOwnSuggestionsBranch } from './branch-name.js';
+export { ORIGIN_FETCH_REFSPEC, SAFE_IMPLICIT_FETCH_ARGS, cloneCredentialArgs, cloneCredentialConfigArgs, cloneTrackingConfigArgs, credentialHelperValue } from './clone-config.js';
+export type { FileChangeNotifier } from './file-change-notifier.js';
+export { GitGuardedFilesystem } from './git-guarded-filesystem.js';
+export { LockingFilesystem, MoveLockedError, MoveRacedError } from './locking-filesystem.js';
+export { ReadOnlyFilesystem } from './read-only-filesystem.js';
+export { normalizeRepositoryAddress, sameRepository } from './remote-url.js';
+export { assertInsideRepo, assertKbDirNameFree, assertRepoRootNameFree, assertRepoRootNameFreeArgs, hasControlCharacter, isInsideRepo, normalizePathArgs } from './repo-path.js';

package/src/modules/kb-fs/locking-filesystem.ts

@@ -55,7 +55,7 @@ import { DestinationTakenError, lstatOrNull, renameNoReplace, takenError } from
 import { linkedAncestor } from '../../shared/no-link-below.js';
 import { assertInsideRepo } from './repo-path.js';
 import { GitGuardedFilesystem } from './git-guarded-filesystem.js';
-import type { CreationGrantPlan, ICreatorAccess } from '../access-model/creator.js';
+import type { CreationGrantPlan, ICreatorAccess } from '../access-model/index.js';
 
 /** How many times to retry a contended acquire before giving up. */
 const ACQUIRE_RETRY_ATTEMPTS = 3;

package/src/modules/kb-sync/kb-sync.routes.ts

@@ -2,12 +2,12 @@ import express from 'express';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('sync');
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import { assertValidBranchName } from '../kb-fs/index.js';
 import type { IKbSyncService, SyncResult } from './kb-sync.interface.js';
 import { parseSyncPayload, type SyncPayloadSource } from './sync-payload.js';
 import { verifySyncCredential } from './sync-auth.js';
-import { AuthBackendError } from '../auth/account-admission.js';
+import { AuthBackendError } from '../auth/index.js';
 
 /**
  * Remote sync — a git host or a pipeline tells Hexis the repository changed.

package/src/modules/kb-sync/kb-sync.service.ts

@@ -2,7 +2,7 @@ import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('sync');
-import { sanitizeError } from '../workflow/sanitize-error.js';
+import { sanitizeError } from '../workflow/index.js';
 import type {
   IKbSyncService,
   LastSync,

package/src/modules/kb-sync/sync-auth.ts

@@ -1,5 +1,5 @@
 import { createHmac } from 'node:crypto';
-import { timingSafeStringEqual } from '../auth/password-hash.js';
+import { timingSafeStringEqual } from '../auth/index.js';
 
 /**
  * Who may call `POST /api/sync`, decided from the request's credentials.

package/src/modules/kb-sync/sync-payload.ts

@@ -1,4 +1,4 @@
-import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import { assertValidBranchName } from '../kb-fs/index.js';
 
 /**
  * Turn whatever a caller POSTed to `/api/sync` into the branches to sync.

package/src/modules/marketplace/git-http.routes.ts

@@ -5,7 +5,7 @@ const log = logger('marketplace');
 import { spawn } from 'node:child_process';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { MarketplaceRepoService } from './marketplace-repo.service.js';
-import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../tool-auth/index.js'; // Express Request augmentation (req.externalApiKeyId)
 
 /** How a bearer string resolves to a user — the connection-key service's shape. */
 export interface MarketplaceKeyResolver {

package/src/modules/marketplace/github-facade/github-facade-admin.routes.ts

@@ -2,7 +2,7 @@ import express from 'express';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('github-facade');
-import '../../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import '../../auth/index.js'; // Express Request.userId / userEmail augmentation
 import {
   GitHubFacadeUnavailableError,
   type GitHubFacadeCredentialsService,

package/src/modules/marketplace/github-facade/github-facade-codes.store.ts

@@ -1,6 +1,6 @@
 import { and, eq, gt, isNull } from 'drizzle-orm';
-import type { Database } from '../../database/connection.js';
-import { githubFacadeCodes } from '../../database/schema.js';
+import type { Database } from '../../database/index.js';
+import { githubFacadeCodes } from '../../database/index.js';
 
 /**
  * A one-time code the consent page issued, waiting for Anthropic's backend

package/src/modules/marketplace/github-facade/github-facade-credentials.service.ts

@@ -1,7 +1,7 @@
 import { generateKeyPairSync, randomBytes, randomInt } from 'node:crypto';
 import { and, eq } from 'drizzle-orm';
-import type { Database } from '../../database/connection.js';
-import { githubFacadeIdentity } from '../../database/schema.js';
+import type { Database } from '../../database/index.js';
+import { githubFacadeIdentity } from '../../database/index.js';
 import type { TokenCrypto } from '../../../shared/token-crypto.js';
 
 /**

package/src/modules/marketplace/github-facade/github-facade.routes.ts

@@ -3,8 +3,8 @@ import { logger } from '../../../shared/logging.js';
 
 const log = logger('github-facade');
 import type { AuthUser } from '@bevel-software/platform-shared';
-import '../../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import '../../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../../auth/index.js'; // Express Request.userId / userEmail augmentation
+import '../../tool-auth/index.js'; // Express Request augmentation (req.externalApiKeyId)
 import type { MarketplaceRepoService } from '../marketplace-repo.service.js';
 import type { MarketplaceKeyResolver } from '../git-http.routes.js';
 import { GitHubFacadeRequestError, type GitHubFacade } from './github-facade.service.js';

package/src/modules/marketplace/github-facade/github-facade.service.ts

@@ -2,8 +2,8 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('github-facade');
-import type { KeyKindSpec, MintedExternalApiKey } from '../../tool-auth/external-api-key.interface.js';
-import { signAuthRequest, type McpAuthRequestState } from '../../mcp/oauth/oauth-state.js';
+import type { KeyKindSpec, MintedExternalApiKey } from '../../tool-auth/index.js';
+import { signAuthRequest, type McpAuthRequestState } from '../../mcp/index.js';
 import type { GitHubFacadeCredentialsService } from './github-facade-credentials.service.js';
 import type { GitHubFacadeCodeStore } from './github-facade-codes.store.js';
 import { printable } from '../../../shared/printable.js';

package/src/modules/marketplace/marketplace-repo.service.ts

@@ -2,8 +2,8 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn, type ChildProcess } from 'node:child_process';
-import { WorkspaceMutex } from '../kb-fs/mutex.js';
-import type { VirtualTree } from '../plugins/compile/compile-marketplace.js';
+import { WorkspaceMutex } from '../kb-fs/index.js';
+import type { VirtualTree } from '../plugins/index.js';
 import { type IGitRunner } from '../../shared/git.contract.js';
 
 /** What the repo service asks the compiler for — the one seam it has. */

package/src/modules/mcp/__tests__/read-only-hint.e2e.test.ts

@@ -0,0 +1,213 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express, { type RequestHandler } from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { createMcpRoutes } from '../mcp.routes.js';
+import { McpService } from '../mcp.service.js';
+import { SpillStore } from '../../workspace/index.js';
+import { TOOL_READ_ONLY_SETTING, ToolReadOnlyHints, ToolRegistry, createManualRoutes } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
+import { createCatalogRevisionRoutes } from '../../../core/catalog-revision.js';
+import { startFakeDownstreamMcpServer, type FakeDownstreamMcpServer } from './fake-downstream-mcp-server.js';
+
+/**
+ * The read-only hint as the HOSTED MCP endpoint lists it, over the real
+ * Streamable-HTTP transport: the real `McpService` discovering the real agent
+ * manual over loopback, with the real hints applied to it. What a client such
+ * as Claude Cowork reads to decide whether a call needs approval.
+ */
+
+const KEY = 'bevel_key_interactive';
+const fakeAuth: RequestHandler = (req, res, next) => {
+  if ((req.headers.authorization ?? '') !== `Bearer ${KEY}`) {
+    res.status(401).json({ error: 'unauthorized' });
+    return;
+  }
+  // An interactive caller (no connection-key id): the full listing, no credential filter.
+  req.userId = 'user-A';
+  next();
+};
+const pass: RequestHandler = (_req, _res, next) => next();
+
+const stops: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const stop of stops.splice(0).reverse()) await stop().catch(() => {});
+});
+
+async function startPlatform(opts: { downstream?: FakeDownstreamMcpServer; catalogRevision?: boolean } = {}) {
+  const registry = new ToolRegistry();
+  registry.registerExternalTool(
+    toolDef({ name: 'read_file', description: 'Read a file.', path: '/api/agent/tools/read_file', inputs: { type: 'object', properties: {} } }),
+  );
+  registry.registerExternalTool(
+    toolDef({
+      name: 'write_file',
+      description: 'Write a file.',
+      path: '/api/agent/tools/write_file',
+      inputs: { type: 'object', properties: {} },
+      tags: ['write'],
+    }),
+  );
+  // One stored row, as the deployment-settings table would hold it.
+  const row = { value: '' };
+  const hints = new ToolReadOnlyHints(registry, {
+    reload: async (key) => (key === TOOL_READ_ONLY_SETTING ? row.value : ''),
+    recordIfAbsent: async (_key, value) => {
+      if (row.value) return false;
+      row.value = value;
+      return true;
+    },
+    swapIfValue: async (_key, expected, next) => {
+      if (row.value !== expected) return false;
+      row.value = next ?? '';
+      return true;
+    },
+  });
+
+  const app = express();
+  app.use(express.json());
+  app.get('/api/agent/all-tools', (_req, res) => {
+    res.json({
+      manuals: [
+        {
+          name: 'KNOWLEDGE_BASE',
+          call_template_type: 'http',
+          http_method: 'GET',
+          url: '${API_URL}/api/agent/utcp',
+          content_type: 'application/json',
+          headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+        },
+        // A plugin's MCP server: a tool from the knowledge base, not the platform's.
+        ...(opts.downstream
+          ? [{ name: 'notion', call_template_type: 'mcp', config: { mcpServers: { srv: { transport: 'http', url: opts.downstream.url } } } }]
+          : []),
+      ],
+    });
+  });
+  const httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, '127.0.0.1', () => resolve(s));
+  });
+  const baseUrl = `http://127.0.0.1:${(httpServer.address() as AddressInfo).port}`;
+  const service = new McpService({
+    loopbackBaseUrl: baseUrl,
+    manualName: 'KNOWLEDGE_BASE',
+    spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    publicFrontendUrl: 'http://localhost:5173',
+    readOnlyOverrides: () => hints.overrides(),
+  });
+  const stub = {} as never;
+  app.use('/api', createMcpRoutes(service, stub, fakeAuth, fakeAuth, stub, stub, stub, ''));
+  app.use('/api', createManualRoutes(registry, pass, undefined, hints));
+  // The route the endpoint keys its cached tool surface by. Served, a listing
+  // reuses the surface it built until the revision moves; absent (404), every
+  // request builds its own. An override does not move it: the hints are
+  // joined on per listing, so the cached surface never holds one.
+  if (opts.catalogRevision) {
+    const asCaller: RequestHandler = (req, _res, next) => {
+      req.toolAuth = { userId: 'user-A' } as never;
+      next();
+    };
+    app.use(
+      '/api',
+      createCatalogRevisionRoutes({
+        toolManuals: { catalogFingerprints: async () => [] },
+        skills: { listSkills: async () => [] },
+        manualAuth: asCaller,
+        resolveUserEmail: async () => 'a@example.test',
+      }),
+    );
+  }
+  stops.push(async () => {
+    service.onSecretsChanged(null);
+    httpServer.closeAllConnections();
+    await new Promise<void>((r) => httpServer.close(() => r()));
+  });
+  return { baseUrl, hints };
+}
+
+async function connect(baseUrl: string): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/api/mcp`), {
+    requestInit: { headers: { Authorization: `Bearer ${KEY}` } },
+  });
+  const client = new Client({ name: 'hint-client', version: '0.0.0' }, { capabilities: {} });
+  await client.connect(transport);
+  stops.push(() => client.close());
+  return client;
+}
+
+const annotationsOf = async (client: Client) =>
+  Object.fromEntries((await client.listTools()).tools.map((t) => [t.name, t.annotations]));
+
+describe('the hosted MCP endpoint lists the read-only hint', () => {
+  it('on every platform tool and every meta-tool, and no other annotation', async () => {
+    const { baseUrl } = await startPlatform();
+    expect(await annotationsOf(await connect(baseUrl))).toEqual({
+      list_tools: { readOnlyHint: true },
+      tools_info: { readOnlyHint: true },
+      call_tool_chain: { readOnlyHint: false },
+      read_file: { readOnlyHint: true },
+      write_file: { readOnlyHint: false },
+    });
+  });
+
+  it("lists an admin's change on the client's NEXT tools/list, with no reconnect, and a reset undoes it", async () => {
+    const { baseUrl, hints } = await startPlatform();
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('call_tool_chain', true, '00000000-0000-4000-8000-00000000000a');
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file', 'call_tool_chain']) await hints.set(name, null, '00000000-0000-4000-8000-00000000000a');
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: false });
+  });
+
+  it("lists an admin's change and its reset on the next tools/list when the tool surface is cached", async () => {
+    const { baseUrl, hints } = await startPlatform({ catalogRevision: true });
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file']) await hints.set(name, null, '00000000-0000-4000-8000-00000000000a');
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+  });
+
+  it('does not keep an override in the cached surface: one set before the surface is built is undone by its reset', async () => {
+    const { baseUrl, hints } = await startPlatform({ catalogRevision: true });
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: false });
+
+    await hints.set('read_file', null, '00000000-0000-4000-8000-00000000000a');
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+  });
+
+  it('leaves a tool from a plugin MCP server unannotated, as before', async () => {
+    const downstream = await startFakeDownstreamMcpServer();
+    stops.push(() => downstream.stop());
+    const { baseUrl } = await startPlatform({ downstream });
+    const tools = (await (await connect(baseUrl)).listTools()).tools;
+    const proxied = tools.find((t) => t.name.endsWith('echo'));
+    expect(proxied).toBeDefined();
+    expect(proxied).not.toHaveProperty('annotations');
+  });
+});

package/src/modules/mcp/index.ts

@@ -0,0 +1,7 @@
+/**
+ * What the mcp 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 { signAuthRequest } from './oauth/oauth-state.js';
+export type { McpAuthRequestState } from './oauth/oauth-state.js';

package/src/modules/mcp/mcp-auth.middleware.ts

@@ -3,14 +3,13 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('mcp-auth');
 import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
-import type { AuthService } from '../auth/auth.service.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE, AccountDeactivatedError, AuthBackendError } from '../auth/account-admission.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
-import { rejectConnectionKey } from '../tool-auth/connection-key-rejection.js';
+import type { AuthService } from '../auth/index.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AccountDeactivatedError, AuthBackendError } from '../auth/index.js';
+import type { IExternalApiKeyService, InternalTokenService } from '../tool-auth/index.js';
+import { rejectConnectionKey } from '../tool-auth/index.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
-import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
-import '../audit/audit.contract.js'; // Express Request augmentation (req.agentConnectionId)
+import '../tool-auth/index.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../audit/index.js'; // Express Request augmentation (req.agentConnectionId)
 
 /** Which of the four credentials below an MCP request was authenticated with. */
 export type McpCallerKind = 'key' | 'oauth' | 'internal' | 'session';

package/src/modules/mcp/mcp.routes.ts

@@ -9,13 +9,11 @@ import {
   InvalidTokenLabelError,
   TokenNotFoundError,
   TokenStillActiveError,
-} from '../tool-auth/external-api-key.errors.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+} from '../tool-auth/index.js';
+import type { IExternalApiKeyService, InternalTokenService, ILlmUsageMeter } from '../tool-auth/index.js';
 import { MCP_LOOPBACK_TOKEN_TTL_MS, type McpService } from './mcp.service.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
-import type { ILlmUsageMeter } from '../tool-auth/llm-usage-meter.js';
-import '../tool-auth/external-api-key.interface.js'; // req.externalApiKeyId augmentation
+import '../tool-auth/index.js'; // req.externalApiKeyId augmentation
 import './mcp-auth.middleware.js'; // req.mcpCallerKind augmentation
 import { isPagePath } from '../audit/index.js';
 

package/src/modules/mcp/mcp.service.ts

@@ -37,6 +37,7 @@ import {
   installSessionRecovery,
   flattenManualTool,
   toListedTool,
+  withReadOnlyOverride,
   toolError,
   retiredToolMessage,
   needsAuthorizationResult,
@@ -49,18 +50,13 @@ import {
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
 import type { KbLayout } from '@bevel-software/platform-shared';
-import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
-import {
-  scopesCovered,
-  type ForcedRefreshOutcome,
-  type ISecretsVaultService,
-} from '../secrets-vault/secrets-vault.contract.js';
-import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
-import type { SpillStore } from '../workspace/spill-store.js';
+import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, scopesCovered } from '../secrets-vault/index.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
+import type { IToolManualService } from '../tool-manuals/index.js';
+import type { SpillStore } from '../workspace/index.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 import { seedBevelHostedManualVars } from '../../shared/utcp-namespace.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import type { InternalTokenService } from '../tool-auth/index.js';
 import { RequestAudit, type IAgentEventRecorder, type RecordedPrincipal } from '../audit/index.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
 import { DownstreamPool, POOL_KEY_SEPARATOR, type DownstreamPoolOptions, type Lease } from './downstream-pool.js';
@@ -78,7 +74,7 @@ import {
   type AgentPreambleReader,
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
-import { guideFirstDescription } from '../tool-registry/guide-first.js';
+import { guideFirstDescription } from '../tool-registry/index.js';
 
 /**
  * Configuration for the loopback proxy. `loopbackBaseUrl` is the backend's own
@@ -123,6 +119,16 @@ export interface McpProxyOptions {
    * knowledge base's.
    */
   secretsScope?: string;
+  /**
+   * The deployment's read-only overrides, by tool name, read per listing so an
+   * admin's change on the Tools page is in the next `tools/list`. Joined on
+   * here, at listing time, for the platform tools and the code-mode meta-tools
+   * alike: the platform tools' BUILT-IN hint arrives as the manual's
+   * `read-only` tag, in a surface that is cached across requests, so an
+   * override baked into it would outlive the toggle that set it. Absent, every
+   * tool lists its built-in hint.
+   */
+  readOnlyOverrides?: () => Promise<Readonly<Record<string, boolean>>>;
 }
 
 /** Who a request is from — everything the proxy needs, resolved from that request's own bearer. */
@@ -553,7 +559,15 @@ export class McpService {
     );
 
     server.setRequestHandler(ListToolsRequestSchema, async () => inRequest(async () => {
-      const [{ tools, catalogNames }, { toolPrefix }] = await Promise.all([requestSurface(), agentInstructions()]);
+      const [{ tools, catalogNames }, { toolPrefix }, readOnly] = await Promise.all([
+        requestSurface(),
+        agentInstructions(),
+        // A failed read lists the built-in hints rather than no listing at all.
+        this.opts.readOnlyOverrides?.().catch((err: unknown) => {
+          log.warn('tools/list: could not read the read-only overrides; listing built-in hints.', { err });
+          return undefined;
+        }),
+      ]);
       // A discovered tool whose name collides with a meta-tool would be
       // listed but never callable (the dispatcher routes the name to the
       // meta-tool first), so drop it from the listing entirely.
@@ -590,7 +604,9 @@ export class McpService {
         // place for it), so it is joined on here — the one point where a
         // discovered tool becomes a listing entry.
         const ui = apps && Object.hasOwn(apps.tools, t.mcpName) ? apps.tools[t.mcpName] : undefined;
-        const entry = toListedTool(ui ? { ...t, ui } : t); // logs its own reason on a name/schema drop
+        // An admin's override of a platform tool's hint, read for THIS listing.
+        const hinted = withReadOnlyOverride(t, readOnly);
+        const entry = toListedTool(ui ? { ...hinted, ui } : hinted); // logs its own reason on a name/schema drop
         if (!entry) {
           dropped.push(t.mcpName);
           continue;
@@ -641,6 +657,7 @@ export class McpService {
       // built here, so here it is.
       const metaTools = codeModeMetaTools(EXTERNAL_KB_MANUAL_NAME, examplePool, {
         sharedRulesPointer: '',
+        ...(readOnly ? { readOnly } : {}),
       }).map((tool) => ({ ...tool, description: guideFirstDescription(tool.description) }));
       // Log only when a tool was dropped (name/schema/duplicate) — that's the
       // anomaly worth surfacing, since a downstream client would otherwise hide

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -21,8 +21,8 @@ import type {
   OAuthTokens,
 } from '@modelcontextprotocol/sdk/shared/auth.js';
 import type { AgentConnectedEvent } from '@bevel-software/platform-shared';
-import type { Database } from '../../database/connection.js';
-import { agentConnections, oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/schema.js';
+import type { Database } from '../../database/index.js';
+import { agentConnections, oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/index.js';
 import type { TokenCrypto } from '../../../shared/token-crypto.js';
 import { signAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 

package/src/modules/mcp/oauth/oauth-consent.routes.ts

@@ -4,7 +4,7 @@ import { logger } from '../../../shared/logging.js';
 const log = logger('mcp-oauth');
 import type { BevelOAuthProvider } from './bevel-oauth-provider.js';
 import { verifyAuthRequest, type McpAuthRequestState } from './oauth-state.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 OAuthConsentRoutesDeps {
   provider: BevelOAuthProvider;

package/src/modules/onboarding/onboarding.routes.ts

@@ -3,7 +3,7 @@ import type { AuthUser } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IStarterPackService } from './onboarding.contract.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId)
+import '../auth/index.js'; // Express Request augmentation (req.userId)
 
 const log = logger('starter-packs');
 

package/src/modules/onboarding/starter-pack.service.ts

@@ -64,11 +64,10 @@ import {
 import { logger } from '../../shared/logging.js';
 import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import type { FileChangeNotifier } from '../kb-fs/file-change-notifier.js';
-import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
-import type { WorkspaceMutex } from '../kb-fs/mutex.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import type { IAccessControl } from '../access/index.js';
+import type { FileChangeNotifier, WorkspaceMutex } from '../kb-fs/index.js';
+import { LockingFilesystem } from '../kb-fs/index.js';
 import type { IFsProbe, ITreeWalker } from '../../shared/fs.contract.js';
 import {
   isUntouchedStarterPage,
@@ -76,7 +75,7 @@ import {
   type FirstRunStarter,
   type FirstRunStarterSource,
   type MayRead,
-} from '../workspace/first-run.js';
+} from '../workspace/index.js';
 import { pluginAccessMd, withCreatorGrants, type PluginSource } from '../plugins/index.js';
 import {
   NO_STARTER_PACK,