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

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';

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

@@ -3,9 +3,9 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('tools');
 import type { IExternalApiKeyService } from './external-api-key.interface.js';
-import type { AuthService } from '../auth/auth.service.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE, AuthBackendError } from '../auth/account-admission.js';
-import { InternalTokenService } from './internal-token.service.js';
+import type { AuthService } from '../auth/index.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AuthBackendError } from '../auth/index.js';
+import type { InternalTokenService } from './internal-token.service.js';
 import {
   INVALID_CONNECTION_KEY_CHALLENGE,
   INVALID_CONNECTION_KEY_MESSAGE,

package/src/modules/tool-helpers/__tests__/agent-roles-write.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 { NEW_ROLE_GUIDANCE } from '../../access-model/roles-yaml-guard.js';
 import { loadActiveGroups } from '../../access/access-control.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -72,7 +72,7 @@ async function start(): Promise<string> {
     // The `after` half of a move's or copy's preview — allowing everything, like the gates above.
     previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
   } as never;
-  registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache), allowAll, testKbContext({ kbDirName: KB }), {
+  registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache, new WorkerDocumentExtractor()), allowAll, testKbContext({ kbDirName: KB }), {
     // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),

package/src/modules/tool-helpers/__tests__/can-write.tools.test.ts

@@ -17,7 +17,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 { AccessControlService } from '../../access/access-control.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
@@ -188,7 +188,7 @@ beforeAll(async () => {
     toolAuth,
     toolHandler,
     spills,
-    new DocExtractService(docCache),
+    new DocExtractService(docCache, new WorkerDocumentExtractor()),
     counted,
     kb,
     { recoveryBotEmail: 'recovery-bot@bevel.local', hooks, notes: new ToolDescriptionNotes() },

package/src/modules/tool-helpers/__tests__/phase4-tools.test.ts

@@ -12,7 +12,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 { testKbContext } from '../../../__tests__/kb-context.js';
 
 const WS = 'target-company-state';
@@ -65,7 +65,7 @@ async function start(): Promise<string> {
   // kb (citation) tools alongside the workspace tools. Those registrations —
   // and their web_search / submit_feedback / cite_kb_node cases — moved to
   // the enterprise repo with their modules; core registers only core tools.
-  registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), new DocExtractService('/tmp/bevel-test-doc-extract'), accessControl, testKbContext(), {
+  registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), new DocExtractService('/tmp/bevel-test-doc-extract', new WorkerDocumentExtractor()), accessControl, testKbContext(), {
     // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),

package/src/modules/tool-helpers/default-branch-write.ts

@@ -1,4 +1,4 @@
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { ToolContext } from './tool.contract.js';
 
 /**

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

@@ -48,9 +48,13 @@ export {
   type BranchDeclaration,
 } from './tool-def.js';
 export { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from './tool.contract.js';
-export type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+export type { JsonSchema, UtcpTool } from '../tool-registry/index.js';
 export {
   CAN_WRITE_CLAUSE,
   defaultBranchWriteVerdicts,
   type DefaultBranchWriteDeps,
 } from './default-branch-write.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { argumentsRefusal } from './route-argument-check.js';
+export { bodyEnvelope, declareRouteTool } from './route-tool-schemas.js';
+export type { ToolHandlerFactory } from './tool-handler.js';

package/src/modules/tool-helpers/route-argument-check.ts

@@ -4,7 +4,7 @@ import {
   argumentsDoNotMatchMessage,
   checkFor,
 } from '@bevel-software/platform-mcp-core';
-import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
 import { branchProvided } from '../../shared/domain-errors.js';
 import { logger } from '../../shared/logging.js';
 import { ToolError } from './tool.contract.js';

package/src/modules/tool-helpers/route-tool-schemas.ts

@@ -1,5 +1,5 @@
 import { logger } from '../../shared/logging.js';
-import type { JsonSchema } from '../tool-registry/tool.contract.js';
+import type { JsonSchema } from '../tool-registry/index.js';
 
 const log = logger('tools');
 

package/src/modules/tool-helpers/tool-context.ts

@@ -1,24 +1,22 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { LocalFilesystem } from '@mastra/core/workspace';
+import type { LocalFilesystem } from '@mastra/core/workspace';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
-import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import { LockingFilesystem, ReadOnlyFilesystem } from '../kb-fs/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';
-import { ReadOnlyFilesystem } from '../kb-fs/read-only-filesystem.js';
 import {
   makeAgentRolesYamlWriteValidator,
   ROLES_YAML_BASENAME,
-} from '../access-model/roles-yaml-guard.js';
-import type { ICreatorAccess } from '../access-model/creator.js';
-import type { GroupsIndex } from '../access-model/group-files.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+} from '../access-model/index.js';
+import type { ICreatorAccess, GroupsIndex } from '../access-model/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { assertBranchProvided } from '../../shared/domain-errors.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
-import type { AuthService } from '../auth/auth.service.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
+import type { AuthService } from '../auth/index.js';
 import { ToolError, type ToolContext } from './tool.contract.js';
-import type { ToolAuth } from '../tool-auth/tool-auth.middleware.js';
+import type { ToolAuth } from '../tool-auth/index.js';
 
 export interface ToolContextDeps {
   authService: AuthService;

package/src/modules/tool-helpers/tool-def.ts

@@ -1,7 +1,7 @@
 import '@utcp/http';
 import { HttpCallTemplateSerializer } from '@utcp/http';
 import { ToolSerializer } from '@utcp/sdk';
-import type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+import type { JsonSchema, UtcpTool } from '../tool-registry/index.js';
 import { declareRouteTool } from './route-tool-schemas.js';
 
 const httpTemplate = new HttpCallTemplateSerializer();
@@ -146,7 +146,9 @@ export interface ToolDefSpec {
   branch?: BranchDeclaration;
   /**
    * The tool writes. A `write` tag says the same. A writing tool cannot
-   * declare `defaults-to-default-branch`.
+   * declare `defaults-to-default-branch`. It is also the tool's built-in
+   * read-only hint to MCP clients: a tool that declares no write is listed
+   * `readOnlyHint: true` (see `tool-registry/read-only-hints.ts`).
    */
   write?: boolean;
 }
@@ -185,7 +187,9 @@ export function toolDef(spec: ToolDefSpec): UtcpTool {
     description: spec.description,
     inputs: wire,
     outputs: spec.outputs ?? { type: 'object', properties: {} },
-    tags: spec.tags ?? [],
+    // `write: true` is carried as the `write` tag too: the tag is what survives
+    // serialization, and what the write gate and the read-only hint read.
+    tags: spec.write ? [...new Set([...(spec.tags ?? []), 'write'])] : (spec.tags ?? []),
     tool_call_template: httpTemplate.validateDict({
       call_template_type: 'http',
       http_method: 'POST',

package/src/modules/tool-helpers/tool-handler.ts

@@ -13,8 +13,8 @@ import { branchHandlingFor, type BranchHandling } from './tool-def.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { ResolveToolContext } from './tool-context.js';
 import { argumentsRefusal } from './route-argument-check.js';
-import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/write-access.js';
-import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
+import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/index.js';
+import '../tool-auth/index.js'; // Express Request.toolAuth augmentation
 
 function isAsyncIterable(v: unknown): v is AsyncIterable<unknown> {
   return (

package/src/modules/tool-helpers/tool.contract.ts

@@ -1,7 +1,7 @@
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import type { LocalFilesystem } from '@mastra/core/workspace';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WorkspaceService } from '../workspace/index.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';
 
 /**

package/src/modules/tool-helpers/validate-token.ts

@@ -1,6 +1,5 @@
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import { InternalTokenService } from '../tool-auth/internal-token.service.js';
-import { createTokenVerifier } from '../tool-auth/tool-auth.middleware.js';
+import type { IExternalApiKeyService, InternalTokenService } from '../tool-auth/index.js';
+import { createTokenVerifier } from '../tool-auth/index.js';
 import { createToolContextResolver, type ToolContextDeps } from './tool-context.js';
 import { ToolError, type ToolContext } from './tool.contract.js';
 

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

@@ -15,3 +15,9 @@ export {
   type ToolCapability,
   type ToolManualType,
 } from './tool-manuals.contract.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { judgeMcpServerEntry } from './mcp-json-discovery.js';
+export type { PortableHttpEntry, PortableStdioEntry } from './mcp-json-discovery.js';
+export { MAX_CAPABILITIES } from './tool-manuals.contract.js';
+export type { ToolHealthCheck, ToolManualDescriptor, ToolProbeTarget, ToolVariable } from './tool-manuals.contract.js';
+export { normalizeToolManual } from './tool-manuals.service.js';

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -6,12 +6,12 @@ import {
   PLUGIN_MCP_FILE,
   type AuthUser,
 } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { validatedVariables } from './mcp-json-discovery.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import { containsVariableReference, findReservedVariableRef } from '../../shared/variable-refs.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { IToolManualService, ToolVariable } from './tool-manuals.contract.js';
 

package/src/modules/tool-manuals/pending-tools.service.ts

@@ -6,9 +6,9 @@ import {
   type IWorkflowService,
   type KbLayout,
 } from '@bevel-software/platform-shared';
-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 { readAt, visibleProposedFiles } from '../../shared/pending-proposals.js';
 import { utcpNamespacePrefix } from '../../shared/utcp-namespace.js';
 import { baseName, normalizeToolManual } from './tool-manuals.service.js';

package/src/modules/tool-manuals/tool-delete.service.ts

@@ -7,15 +7,14 @@ import {
   PLUGIN_MCP_FILE,
   type AuthUser,
 } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { utcpNamespacePrefix } from '../../shared/utcp-namespace.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { IFsProbe } from '../../shared/fs.contract.js';
-import type { ISkillService } from '../skills/skills.contract.js';
-import type { IPluginIndexService, PluginCatalogEntry } from '../plugins/plugins.contract.js';
-import type { PluginSource } from '../plugins/discovery/plugin-source.js';
-import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
+import type { ISkillService } from '../skills/index.js';
+import type { IPluginIndexService, PluginCatalogEntry, PluginSource } from '../plugins/index.js';
+import type { ISecretsVaultService } from '../secrets-vault/index.js';
 import type { IToolManualService, ToolManualSummary } from './tool-manuals.contract.js';
 
 /**

package/src/modules/tool-manuals/tool-manuals.routes.ts

@@ -5,19 +5,19 @@ const log = logger('tool-manuals');
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import AdmZip from 'adm-zip';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { isAbsence, type IFsProbe, type ITreeWalker } from '../../shared/fs.contract.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import type { IPluginIndexService } from '../plugins/plugins.contract.js';
+import type { IAccessControl } from '../access/index.js';
+import type { IPluginIndexService } from '../plugins/index.js';
 import '@utcp/http'; // side effect: register the 'http' call-template type
 import { CallTemplateSerializer, type CallTemplate } from '@utcp/sdk';
 import { type IPendingToolService, type IToolManualService, EXTERNAL_KB_MANUAL_NAME } from './tool-manuals.contract.js';
 import { McpServerEditError, type McpServerEditService, type McpServerWrite } from './mcp-server-edit.service.js';
 import { ToolDeleteError, type ToolDeleteService } from './tool-delete.service.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
-import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
+import '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
+import '../tool-auth/index.js'; // Express Request augmentation (req.toolAuth)
 import { hasGitInternalsSegment } from '../../shared/git-internals.js';
 
 /** Resolve a connection-key/internal-token user id to its email (per-caller ACL). */

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -20,11 +20,11 @@ import {
 // auth type, so a `.tool` naming it validates here.
 import { findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey } from '@bevel-software/platform-mcp-core';
 import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
-import type { PluginSource } from '../plugins/discovery/plugin-source.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { PluginSource } from '../plugins/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import { redactSecret } from '../../shared/redact-secret.js';
 import { printable } from '../../shared/printable.js';

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -1,11 +1,9 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import { declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { ToolContext, ToolHandlerFactory } from '../tool-helpers/index.js';
+import { toolDef, declareRouteTool } from '../tool-helpers/index.js';
+import type { IAccessControl } from '../access/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IToolManualService } from './tool-manuals.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';