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

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 { ISkillService } from './skills.contract.js';
-import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.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, SkillScope } from './skills.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
@@ -134,9 +130,13 @@ export function registerSkillsTools(
     return { paths: committed.includes(skillMdOf(loaded)) ? committed : [skillMdOf(loaded), ...loaded.files], at };
   };
 
-  registry.registerExternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
+  registry.registerExternalTool((ctx) =>
+    buildListSkillsDef(skillService, ctx.userEmail, ctx.connectionScope?.skillFilter()),
+  );
   registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
-  registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+  registry.registerExternalTool((ctx) =>
+    buildGetSkillDef(skillService, ctx.userEmail, ctx.connectionScope?.skillFilter()),
+  );
   registry.registerInternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
   // Both defs are built per catalog listing (their descriptions name the skills
   // THIS caller may read), so declare the arguments here as well: a direct REST
@@ -144,17 +144,24 @@ export function registerSkillsTools(
   declareRouteTool('list_skills', LIST_SKILLS_INPUTS);
   declareRouteTool('get_skill', GET_SKILL_INPUTS);
 
+  // Both skill routes are also how prompts are read (`discovery`): a
+  // connection made as an agent configuration that names skills has them as
+  // prompts even when its `platformTools` does not offer these two tools.
   router.post(
     '/agent/tools/list_skills',
     toolAuth,
     toolHandler(async (args, ctx: ToolContext) => {
-      const skills = await skillService.listSkills(ctx.user.email, { branch: branchArg(args) });
+      const within = ctx.connectionScope?.skillFilter();
+      const skills = await skillService.listSkills(ctx.user.email, {
+        branch: branchArg(args),
+        ...(within ? { within } : {}),
+      });
       // Judged on each skill's SKILL.md, by the default branch's rules — a
       // skill only on a draft is judged where it would land. Each verdict goes
       // onto a COPY: the summaries may be the catalog shared across users.
       const verdicts = await verdictsFor(ctx, skills.map(skillMdOf));
       return { skills: skills.map((s) => ({ ...s, canWrite: verdicts.get(skillMdOf(s)) === true })) };
-    }),
+    }, { discovery: true }),
   );
 
   router.post(
@@ -178,7 +185,12 @@ export function registerSkillsTools(
           400,
         );
       }
-      const result = await skillService.getSkill(ctx.user.email, name, file, { version, branch });
+      const within = ctx.connectionScope?.skillFilter();
+      const result = await skillService.getSkill(ctx.user.email, name, file, {
+        version,
+        branch,
+        ...(within ? { within } : {}),
+      });
       if (!result.ok) return result;
       if (result.kind === 'file') {
         const verdicts = await verdictsFor(ctx, [result.file.path]);
@@ -197,7 +209,7 @@ export function registerSkillsTools(
       };
       if (!allowedTools) return { ...result, skill };
       return { ...result, skill, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
-    }),
+    }, { discovery: true }),
   );
 }
 
@@ -227,8 +239,13 @@ function branchArg(args: Record<string, unknown>): string | undefined {
  * the tool's fixed text leaves under {@link TOOL_DESCRIPTION_CAP} once the
  * guide-first sentence the registry puts in front is counted.
  */
-async function availableSkillsLine(skillService: ISkillService, userEmail: string | undefined, budget: number): Promise<string> {
-  const skills = await skillService.listSkills(userEmail);
+async function availableSkillsLine(
+  skillService: ISkillService,
+  userEmail: string | undefined,
+  budget: number,
+  within?: SkillScope,
+): Promise<string> {
+  const skills = await skillService.listSkills(userEmail, within ? { within } : {});
   if (skills.length === 0) return 'No skills are currently available.';
   const names = skills.map((s) => `\`${s.name}\``);
   const rest = (shown: number): string =>
@@ -280,12 +297,17 @@ const LIST_SKILLS_DESCRIPTION =
   'Each skill carries `canWrite`: whether you may change its SKILL.md directly on the default branch. ' +
   `${CAN_WRITE_CLAUSE} `;
 
-async function buildListSkillsDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
+async function buildListSkillsDef(skillService: ISkillService, userEmail?: string, within?: SkillScope): Promise<UtcpTool> {
   return toolDef({
     name: 'list_skills',
     description:
       LIST_SKILLS_DESCRIPTION +
-      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('list_skills', LIST_SKILLS_INPUTS, LIST_SKILLS_DESCRIPTION))),
+      (await availableSkillsLine(
+        skillService,
+        userEmail,
+        skillsLineBudget('list_skills', LIST_SKILLS_INPUTS, LIST_SKILLS_DESCRIPTION),
+        within,
+      )),
     path: '/api/agent/tools/list_skills',
     inputs: LIST_SKILLS_INPUTS,
     outputs: {
@@ -338,12 +360,17 @@ const GET_SKILL_DESCRIPTION =
   'The skill (or `file`) carries `canWrite`: whether you may change all of it directly on the default branch. ' +
   `${CAN_WRITE_CLAUSE} `;
 
-async function buildGetSkillDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
+async function buildGetSkillDef(skillService: ISkillService, userEmail?: string, within?: SkillScope): Promise<UtcpTool> {
   return toolDef({
     name: 'get_skill',
     description:
       GET_SKILL_DESCRIPTION +
-      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('get_skill', GET_SKILL_INPUTS, GET_SKILL_DESCRIPTION))),
+      (await availableSkillsLine(
+        skillService,
+        userEmail,
+        skillsLineBudget('get_skill', GET_SKILL_INPUTS, GET_SKILL_DESCRIPTION),
+        within,
+      )),
     path: '/api/agent/tools/get_skill',
     inputs: GET_SKILL_INPUTS,
     outputs: {

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

@@ -150,6 +150,7 @@ describe('ExternalApiKeyService', () => {
         revokedAt: null,
         revokedBy: null,
         deletedAt: null,
+        agentPath: null,
       });
     });
 
@@ -370,6 +371,7 @@ describe('ExternalApiKeyService', () => {
         revokedAt: null,
         revokedBy: null,
         deletedAt: null,
+        agentPath: null,
       });
       expect(summaries[1].revokedAt).toBe(rows[1].revokedAt!.getTime());
       // sanity-check that ordering was requested (we can't introspect the
@@ -401,6 +403,7 @@ describe('ExternalApiKeyService', () => {
           revokedAt: null,
           revokedBy: null,
           deletedAt: null,
+          agentPath: null,
           user: { id: 'u-alice', email: 'alice@example.com', name: 'Alice' },
         },
         {
@@ -412,6 +415,7 @@ describe('ExternalApiKeyService', () => {
           revokedAt: bobKey.revokedAt!.getTime(),
           revokedBy: null,
           deletedAt: null,
+          agentPath: null,
           user: { id: 'u-bob', email: 'bob@example.com', name: 'Bob' },
         },
       ]);

package/src/modules/tool-auth/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.interface.ts

@@ -43,6 +43,11 @@ export interface ExternalApiKeySummary {
    * its row stays so the Audit log's events keep their principal.
    */
   deletedAt: number | null;
+  /**
+   * The agent configuration the key connects as (a repo-relative knowledge-base
+   * path), or null for Everything — chosen when the key was minted.
+   */
+  agentPath: string | null;
 }
 
 /** Who revoked a key: its owner, or an admin acting across the deployment. */
@@ -97,6 +102,11 @@ export interface KeyKindSpec {
  */
 export interface MintOptions {
   kind?: string;
+  /**
+   * The agent configuration the key connects as, already checked to be one the
+   * owner may choose (`IAgentScopeResolver.choosable`). Absent: Everything.
+   */
+  agentPath?: string;
 }
 
 /**
@@ -138,7 +148,7 @@ export interface IExternalApiKeyService {
    */
   verifyAndLoadToken(
     plaintext: string,
-  ): Promise<{ tokenId: string; user: AuthUser } | null>;
+  ): Promise<{ tokenId: string; user: AuthUser; agentPath?: string | null } | null>;
 
   /**
    * For a key {@link verifyAndLoadToken} refused: whether it is a live key

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

@@ -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,
@@ -89,7 +89,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
     const [row] = await this.db
       .insert(externalApiKeys)
-      .values({ userId, tokenHash, label: trimmed, kind })
+      .values({ userId, tokenHash, label: trimmed, kind, ...(options.agentPath ? { agentPath: options.agentPath } : {}) })
       .returning();
 
     return {
@@ -118,7 +118,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
   async verifyAndLoadToken(
     plaintext: string,
-  ): Promise<{ tokenId: string; user: AuthUser } | null> {
+  ): Promise<{ tokenId: string; user: AuthUser; agentPath: string | null } | null> {
     if (!this.looksLikeExternalApiKey(plaintext)) {
       return null;
     }
@@ -135,6 +135,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
         tokenId: externalApiKeys.id,
         label: externalApiKeys.label,
         lastUsedAt: externalApiKeys.lastUsedAt,
+        agentPath: externalApiKeys.agentPath,
         userId: users.id,
         email: users.email,
         name: users.name,
@@ -176,6 +177,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
     return {
       tokenId: row.tokenId,
+      agentPath: row.agentPath,
       user: {
         id: row.userId,
         email: row.email,
@@ -353,5 +355,6 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
     revokedBy: (row.revokedBy as RevokedBy | null) ?? null,
     deletedAt: row.deletedAt ? row.deletedAt.getTime() : null,
+    agentPath: row.agentPath ?? null,
   };
 }

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

@@ -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 { ConnectionChoices, ToolAuth } from './tool-auth.middleware.js';
+import './tool-auth.middleware.js';

package/src/modules/tool-auth/internal-token.service.ts

@@ -47,6 +47,15 @@ export interface InternalTokenClaim {
    * internal token.
    */
   connectionId?: string;
+  /**
+   * The agent configuration the external caller's connection was made as (a
+   * repo-relative knowledge-base path), copied at mint from the verified
+   * grant or connection — the hosted proxy's loopback token and the local
+   * server's exchanged grant both carry it, so every agent surface narrows
+   * their calls to that agent's scope (`modules/agent-scope`). Absent is
+   * Everything. Carried, never decided, like `connectionId`.
+   */
+  agentPath?: string;
 }
 
 interface SignedPayload extends InternalTokenClaim {
@@ -148,6 +157,7 @@ export class InternalTokenService {
       ...(typeof payload.focusedBranch === 'string' ? { focusedBranch: payload.focusedBranch } : {}),
       ...(payload.externalProxy === true ? { externalProxy: true } : {}),
       ...(typeof payload.connectionId === 'string' ? { connectionId: payload.connectionId } : {}),
+      ...(typeof payload.agentPath === 'string' && payload.agentPath ? { agentPath: payload.agentPath } : {}),
     };
   }
 

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,
@@ -47,6 +47,13 @@ export interface ToolAuth {
    * recorder attributes a direct tool call to.
    */
   connectionId?: string;
+  /**
+   * The agent configuration an EXTERNAL caller's connection was made as — a
+   * connection key's `api_tokens.agent_path`, or the one an `externalProxy`
+   * token carries for an agent connection. Absent is Everything. Every agent
+   * surface resolves it to the connection's scope (`modules/agent-scope`).
+   */
+  agentPath?: string;
   /** Always `'write'` now (the middleware sets it for both internal + external — neither credential carries scope). The read path is dormant until consumer agents are removed. */
   scope: 'read' | 'write';
 }
@@ -114,6 +121,14 @@ export type VerifyResult =
   | { ok: true; auth: ToolAuth }
   | { ok: false; status: number; message: string; challenge?: string };
 
+/**
+ * A live agent connection's current "Connect as" choice, or null when it is
+ * gone or revoked — what `BevelOAuthProvider.liveConnectionChoice` answers.
+ */
+export interface ConnectionChoices {
+  liveConnectionChoice(connectionId: string): Promise<{ agentPath: string | null } | null>;
+}
+
 /**
  * The framework-agnostic verify core: bearer token (the value AFTER `Bearer `) →
  * normalized `ToolAuth`, accepting EITHER a `bevel_…` connection key (external —
@@ -135,6 +150,14 @@ export function createTokenVerifier(
    * it; absent, internal tokens are judged on their signature alone.
    */
   accounts?: Pick<AuthService, 'isActive'>,
+  /**
+   * Where an `externalProxy` token that names an agent connection reads the
+   * connection's CURRENT choice: the token outlives a re-consent, so the
+   * agent it was minted with may no longer be the one chosen. A
+   * connection no longer live (revoked, deleted) refuses the token. Absent,
+   * the token's own choice stands.
+   */
+  connections?: ConnectionChoices,
 ): (token: string | undefined) => Promise<VerifyResult> {
   const missing = { ok: false as const, status: 401, message: 'A connection key or internal token is required' };
   return async (token) => {
@@ -152,6 +175,13 @@ export function createTokenVerifier(
       if (accounts && !(await accounts.isActive(claim.userId))) {
         return { ok: false, status: 401, message: ACCOUNT_DEACTIVATED_MESSAGE };
       }
+      let agentPath = claim.agentPath;
+      if (claim.externalProxy && claim.connectionId && connections) {
+        const live = await connections.liveConnectionChoice(claim.connectionId);
+        // A revoked connection's token is dead here too, as it is at the MCP endpoint.
+        if (!live) return { ok: false, status: 401, message: 'Access for this agent was revoked' };
+        agentPath = live.agentPath ?? undefined;
+      }
       return claim.externalProxy
         ? {
             ok: true,
@@ -159,6 +189,7 @@ export function createTokenVerifier(
               source: 'external',
               userId: claim.userId,
               ...(claim.connectionId ? { connectionId: claim.connectionId } : {}),
+              ...(agentPath ? { agentPath } : {}),
               scope: 'write',
             },
           }
@@ -169,7 +200,16 @@ export function createTokenVerifier(
     if (externalApiKeyService.looksLikeExternalApiKey(token)) {
       const resolved = await externalApiKeyService.verifyAndLoadToken(token);
       if (resolved) {
-        return { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } };
+        return {
+          ok: true,
+          auth: {
+            source: 'external',
+            userId: resolved.user.id,
+            tokenId: resolved.tokenId,
+            ...(resolved.agentPath ? { agentPath: resolved.agentPath } : {}),
+            scope: 'write',
+          },
+        };
       }
       // A live key of a switched-off account is told so, not sent to mint another.
       if (await externalApiKeyService.isKeyOfSwitchedOffAccount?.(token)) {
@@ -192,8 +232,9 @@ export function createToolAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
   accounts?: Pick<AuthService, 'isActive'>,
+  connections?: ConnectionChoices,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, accounts);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, accounts, connections);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -233,8 +274,9 @@ export function createManualAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
   authService: Pick<AuthService, 'isActive' | 'resolveSession'>,
+  connections?: ConnectionChoices,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, authService, connections);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {

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,14 +17,16 @@ 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';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { BranchNotFoundError } from '../../../shared/domain-errors.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import { SkillService, registerSkillsTools } from '../../skills/index.js';
+import { registerSkillsTools } from '../../skills/index.js';
+// The service itself, from its file: the module entry offers it as a type only.
+import { SkillService } from '../../skills/skills.service.js';
 import { defaultBranchWriteVerdicts } from '../index.js';
 
 /**
@@ -188,7 +190,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,23 @@
 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';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 
 export interface ToolContextDeps {
   authService: AuthService;
@@ -42,6 +41,12 @@ export interface ToolContextDeps {
   loadActiveGroups?: (
     read: (filename: string) => Promise<string | null>,
   ) => Promise<{ groups: GroupsIndex; sourceFile: string; health: { ok: boolean } }>;
+  /**
+   * Resolves the scope of a connection made as an agent configuration. Every
+   * deployment passes it. Absent, a credential that names an agent loads
+   * nothing — a narrowing that cannot be read is never read as Everything.
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>;
 }
 
 /** A file's text, or null when it does not exist. Any other failure throws. */
@@ -151,9 +156,12 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       return fs;
     };
 
+    const connectionScope = await resolveConnectionScope(deps.agentScope, user.email, auth.agentPath);
+
     return {
       user,
       scope: auth.scope,
+      connectionScope,
       source: auth.source,
       tokenId: auth.tokenId,
       // For `internal` callers the signed token claim is the ONLY trustworthy

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