@bevel-software/platform-core-backend 0.20.0 → 0.21.0

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

@@ -13,6 +13,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { GitService } from '../../workflow/git/git.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -53,7 +54,7 @@ describe('SkillService', () => {
   } as unknown as IAccessControl;
 
   const svc = (access: IAccessControl = allowAll) =>
-    new SkillService(workspaceService, access, KB_DIR, new NodeFs());
+    new SkillService(workspaceService, access, testKbContext({ kbDirName: KB_DIR }), new NodeFs());
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
@@ -377,7 +378,7 @@ describe('SkillService', () => {
 
     const versioned = (access: IAccessControl = allowAll) => {
       const service = svc(access);
-      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), KB_DIR));
+      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), testKbContext({ kbDirName: KB_DIR })));
       return service;
     };
 

package/src/modules/skills/allowed-tools-check.ts

@@ -1,5 +1,5 @@
-import { PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 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,
@@ -236,11 +236,12 @@ function editDistance(a: string, b: string): number {
  * Accepts the workspace spelling (`<kbDirName>/Plugins/…`) the save
  * surfaces receive.
  */
-export function skillFileRepoPath(kbDirName: string, workspacePath: string): string | null {
+export function skillFileRepoPath(kb: Pick<KbContext, 'kbDirName' | 'layout'>, workspacePath: string): string | null {
   const parts = workspacePath.split('/').filter((p) => p && p !== '.');
-  if (parts[0] === kbDirName) parts.shift();
+  if (parts[0] === kb.kbDirName) parts.shift();
   if (parts.length < 3 || parts[parts.length - 1] !== 'SKILL.md') return null;
-  return parts[0] === PLUGINS_DIR || parts[0] === SKILLS_DIR ? parts.join('/') : null;
+  const { pluginsDir, skillsDir } = kb.layout;
+  return parts[0] === pluginsDir || parts[0] === skillsDir ? parts.join('/') : null;
 }
 
 /** What the save surfaces and `get_skill` depend on. */
@@ -267,7 +268,7 @@ export class AllowedToolsChecker implements IAllowedToolsChecker {
   constructor(
     private readonly registry: Pick<IToolRegistry, 'listExternal'>,
     private readonly manuals: Pick<IToolManualService, 'listAccessible' | 'getDetail'>,
-    private readonly kbDirName: string,
+    private readonly kb: Pick<KbContext, 'kbDirName' | 'layout'>,
     /**
      * The cap `getDetail` applies to a manual's capabilities. Taken from the
      * projection itself: a copy of the number here would silently start
@@ -300,7 +301,7 @@ export class AllowedToolsChecker implements IAllowedToolsChecker {
    * fail because a check could not run).
    */
   private declaredTools(workspacePath: string, content: string): readonly string[] | undefined {
-    if (skillFileRepoPath(this.kbDirName, workspacePath) === null) return undefined;
+    if (skillFileRepoPath(this.kb, workspacePath) === null) return undefined;
     try {
       return parseSkillFrontmatter(content).allowedTools;
     } catch (err) {

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

@@ -1,9 +1,7 @@
-import {
-  PLUGINS_DIR,
-  SKILLS_DIR,
-} from '@bevel-software/platform-shared';
+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 { 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';
@@ -40,6 +38,7 @@ export class PendingSkillsService implements IPendingSkillService {
     private readonly accessControl: IAccessControl,
     private readonly skillService: ISkillService,
     private readonly workflow: IWorkflowService,
+    private readonly kb: KbContext,
   ) {}
 
   async listPendingSkills(userEmail: string): Promise<PendingSkill[]> {
@@ -54,14 +53,16 @@ export class PendingSkillsService implements IPendingSkillService {
       return [];
     }
 
+    const layout = this.kb.layout;
     const proposed = await visibleProposedFiles(
       {
         workspaceService: this.workspaceService,
         accessControl: this.accessControl,
         workflow: this.workflow,
+        kb: this.kb,
       },
       userEmail,
-      (p) => isSkillDoc(p) && !released.has(folderOf(p)),
+      (p) => isSkillDoc(p, layout) && !released.has(folderOf(p)),
     );
 
     const out: PendingSkill[] = proposed.map(({ cr, path, content, isAuthor }) => {
@@ -96,12 +97,12 @@ export class PendingSkillsService implements IPendingSkillService {
  * catalog already supports. `Plugins/<plugin>/SKILL.md` is NOT a skill — a plugin
  * folder is not itself one.
  */
-function isSkillDoc(repoRelPath: string): boolean {
+function isSkillDoc(repoRelPath: string, layout: KbLayout): boolean {
   const segments = repoRelPath.split('/');
   if (segments[segments.length - 1] !== SKILL_DOC) return false;
   // Under `Skills/` a skill may sit directly below the root: `Skills/<skill>/SKILL.md`.
-  if (segments[0] === SKILLS_DIR) return segments.length >= 3;
-  return segments.length >= 4 && segments[0] === PLUGINS_DIR;
+  if (segments[0] === layout.skillsDir) return segments.length >= 3;
+  return segments.length >= 4 && segments[0] === layout.pluginsDir;
 }
 
 /** The skill folder holding a SKILL.md. */

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

@@ -4,7 +4,6 @@ import { logger } from '../../shared/logging.js';
 const log = logger('skills');
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
 import {
-  DEFAULT_BRANCH,
   joinBranchFor,
   type AuthUser,
   type IWorkflowService,
@@ -14,7 +13,7 @@ import { spliceGrant } from '../access-model/access-splice.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.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 { ISkillService } from './skills.contract.js';
@@ -46,12 +45,13 @@ export function createSkillAccessRequestRoutes(deps: {
   workflow: IWorkflowService;
   workspaceService: WorkspaceService;
   joinRequests: JoinRequestsService;
-  kbDirName: string;
+  kb: KbContext;
   resolveUser: (req: express.Request) => Promise<AuthUser | null>;
 }): express.Router {
-  const { skillService, accessControl, workflow, workspaceService, joinRequests, kbDirName, resolveUser } = deps;
+  const { skillService, accessControl, workflow, workspaceService, joinRequests, kb, resolveUser } = deps;
+  const { kbDirName } = kb;
   const router = express.Router();
-  const wsId = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  const wsId = () => kb.defaultWorkspaceId();
   const rulesOf = (folder: string) => `${folder}/access.md`;
 
   /** The skill the caller may read, by name — or null after answering 404. */
@@ -108,7 +108,7 @@ export function createSkillAccessRequestRoutes(deps: {
         );
       if (!(await branchExists())) {
         try {
-          await workflow.createBranch(wsId(), branch, DEFAULT_BRANCH);
+          await workflow.createBranch(wsId(), branch, kb.defaultBranch);
         } catch (err) {
           if (!(await branchExists())) throw err;
         }
@@ -133,7 +133,7 @@ export function createSkillAccessRequestRoutes(deps: {
       }
       const detail = await workflow.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
-        targetBranch: DEFAULT_BRANCH,
+        targetBranch: kb.defaultBranch,
         title: `Access request: ${name}`,
         description:
           `${user.name} asked to edit the skill ${name}. An editor of the skill accepts by ` +

package/src/modules/skills/skills.routes.ts

@@ -1,7 +1,6 @@
 import express from 'express';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+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';
 
@@ -37,6 +36,8 @@ export interface SkillMembershipGate {
  */
 export function createSkillsRoutes(
   skillService: ISkillService,
+  /** The released branch's clone — where the discoverability verdicts are read. */
+  kb: Pick<KbContext, 'defaultWorkspaceId'>,
   pendingSkills?: IPendingSkillService,
   links?: SkillMembershipSource,
   /**
@@ -75,7 +76,7 @@ export function createSkillsRoutes(
         const folders = [...membership.byPlugin.entries()];
         const verdicts = folders.length
           ? await gate.canReadBatch(
-              workspaceIdForBranch(DEFAULT_BRANCH),
+              kb.defaultWorkspaceId(),
               email,
               folders.map(([, p]) => `${p.folder}/access.md`),
             )

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

@@ -4,9 +4,8 @@ import { logger } from '../../shared/logging.js';
 const log = logger('skills');
 import fs from 'node:fs/promises';
 import { parseDocument } from 'yaml';
-import { DEFAULT_BRANCH, PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.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 { extractFrontmatter, resolveDeclaredId, dedupeById } from '../../shared/frontmatter-id.js';
 import type { IgnoreRules, ITreeWalker } from '../../shared/fs.contract.js';
@@ -54,13 +53,17 @@ export class SkillService implements ISkillService {
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly disk: ITreeWalker,
     now: () => number = Date.now,
   ) {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   /** Attach the history source a `version` is answered from. */
   setHistory(history: SkillHistorySource): void {
     this.history = history;
@@ -92,7 +95,7 @@ export class SkillService implements ISkillService {
     const found = (await this.scan()).find((s) => s.summary.name === name);
     if (!found) return { ok: false, error: 'not_found' };
 
-    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    const wsId = this.kb.defaultWorkspaceId();
     // Through `readable`, not a bare `canRead`: the two gates must never
     // disagree. `canRead` reads a file's own frontmatter rules off disk on
     // every call while `canReadBatch` resolves them through a per-workspace
@@ -213,7 +216,7 @@ export class SkillService implements ISkillService {
    */
   private async readable(userEmail: string, skillFolders: string[]): Promise<Map<string, boolean>> {
     return this.accessControl.canReadBatch(
-      workspaceIdForBranch(DEFAULT_BRANCH),
+      this.kb.defaultWorkspaceId(),
       userEmail,
       skillFolders.map((p) => `${p}/SKILL.md`),
     );
@@ -238,7 +241,7 @@ export class SkillService implements ISkillService {
     // be read.
     let wsId: string;
     try {
-      wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+      wsId = (await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch)).id;
     } catch {
       return [];
     }
@@ -314,15 +317,16 @@ export class SkillService implements ISkillService {
     // Each root starts its own ignore stack (the walk extends it with the
     // root's own file first). Order is cosmetic: the sort below is by name
     // then path, so a same-named pair resolves the same way regardless.
-    await walkRoot(SKILLS_DIR);
-    await walkRoot(PLUGINS_DIR);
+    const { skillsDir, pluginsDir } = this.kb.layout;
+    await walkRoot(skillsDir);
+    await walkRoot(pluginsDir);
     // A skill's id (frontmatter `id`/`name`, else folder name) is how getSkill()
     // resolves it, so it must be unique. Sort by (name, root, path) for a
     // deterministic winner — the shared root FIRST, since `Skills/` is a
     // skill's canonical home and a same-named inline copy is the stale one —
     // then REFUSE later duplicates via the shared dedup — the same rule tools
     // use (no silent auto-suffix that would rebind an id under the caller).
-    const rootRank = (p: string) => (p === SKILLS_DIR || p.startsWith(`${SKILLS_DIR}/`) ? 0 : 1);
+    const rootRank = (p: string) => (p === skillsDir || p.startsWith(`${skillsDir}/`) ? 0 : 1);
     out.sort(
       (a, b) =>
         a.summary.name.localeCompare(b.summary.name) ||

package/src/modules/tool-helpers/__tests__/agent-roles-write.test.ts

@@ -16,6 +16,7 @@ import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.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';
 
 /**
  * The agent's file tools over the production context resolver and a real
@@ -68,10 +69,10 @@ async function start(): Promise<string> {
     canWriteBatchAtRef: async () => null,
     canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
   } as never;
-  registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache), allowAll, KB, {
+  registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache), allowAll, testKbContext({ kbDirName: KB }), {
     service: {} as never,
     enabled: false, // ontology boundary not under test here
-    kbDirName: KB,
+    kb: testKbContext({ kbDirName: KB }),
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
   }, new RoutineWritePolicyService(), {} as never);

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

@@ -12,6 +12,7 @@ import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const WS = 'target-company-state';
 let recorded: unknown[][] = [];
@@ -63,10 +64,10 @@ 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, 'knowledge-base', {
+  registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), new DocExtractService('/tmp/bevel-test-doc-extract'), accessControl, testKbContext(), {
     service: {} as never,
     enabled: false, // ontology boundary not under test here
-    kbDirName: 'knowledge-base',
+    kb: testKbContext(),
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
   }, new RoutineWritePolicyService(), {} as never /* sessionSink — start_session not exercised here */);

package/src/modules/tool-manuals/__tests__/mcp-json-discovery.test.ts

@@ -1,8 +1,13 @@
 import { describe, expect, it, vi, afterEach } from 'vitest';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { descriptorsFromMcpJson, judgeMcpServerEntry } from '../mcp-json-discovery.js';
 
 afterEach(() => vi.restoreAllMocks());
 
+/** The reader under the default layout, which these cases are written against. */
+const fromMcpJson = (folder: string, mcpJson: string, manifest: string | null) =>
+  descriptorsFromMcpJson(folder, mcpJson, manifest, DEFAULT_KB_LAYOUT);
+
 describe('judgeMcpServerEntry', () => {
   it('keeps every accepted header and env key — one spelled __proto__ included', () => {
     // Parsed from text, as a repository file is: JSON.parse makes `__proto__`
@@ -44,7 +49,7 @@ const MANIFEST = JSON.stringify({
 
 describe('descriptorsFromMcpJson', () => {
   it('synthesizes descriptors keyed by server name, path at mcp.json', () => {
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({ mcpServers: { notion: { type: 'streamable-http', url: 'https://mcp.notion.com/mcp' } } }),
       null,
@@ -63,7 +68,7 @@ describe('descriptorsFromMcpJson', () => {
   it('refuses an sse server rather than rebuilding it as a transport it is not', () => {
     // The pinned MCP client has no sse transport; emitting `http` for an sse
     // server configures a handshake the server does not speak.
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({ mcpServers: { legacy: { type: 'sse', url: 'https://mcp.legacy.example/sse' } } }),
       null,
@@ -72,7 +77,7 @@ describe('descriptorsFromMcpJson', () => {
   });
 
   it('merges extension auth over mcp.json literals and carries variables + description', () => {
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({
         mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp', headers: { 'X-V': '2' } } },
@@ -87,7 +92,7 @@ describe('descriptorsFromMcpJson', () => {
   });
 
   it('marks extension-flagged servers and every stdio server local-only', () => {
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({
         mcpServers: {
@@ -105,7 +110,7 @@ describe('descriptorsFromMcpJson', () => {
 
   it('skips a malformed entry without losing its siblings', () => {
     vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({
         mcpServers: {
@@ -123,7 +128,7 @@ describe('descriptorsFromMcpJson', () => {
   it('ignores malformed extension headers instead of spreading them into keys', () => {
     // A string spread into the merge would scatter its indices ('0', '1', …)
     // into header names; a malformed extension must cost its own data only.
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({
         mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp', headers: { 'X-V': '2' } } },
@@ -142,7 +147,7 @@ describe('descriptorsFromMcpJson', () => {
     // A dropped declaration would silently re-scope a credential (undeclared
     // defaults to the shared admin row), so a bad entry takes the SERVER
     // offline — never just the entry, and never its siblings.
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({
         mcpServers: {
@@ -165,7 +170,7 @@ describe('descriptorsFromMcpJson', () => {
   it('applies the .tool declaration rules: no reserved names, no duplicates, gated OAuth URLs, string authParams', () => {
     vi.spyOn(console, 'warn').mockImplementation(() => {});
     const declare = (variables: unknown) =>
-      descriptorsFromMcpJson(
+      fromMcpJson(
         'GTM',
         JSON.stringify({ mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),
         JSON.stringify({
@@ -197,7 +202,7 @@ describe('descriptorsFromMcpJson', () => {
   });
 
   it('trims a padded oauth clientId like the .tool parser does', () => {
-    const out = descriptorsFromMcpJson(
+    const out = fromMcpJson(
       'GTM',
       JSON.stringify({ mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),
       JSON.stringify({
@@ -225,7 +230,7 @@ describe('descriptorsFromMcpJson', () => {
   it('accepts a client-id-only sign-in (endpoints discovered later), refuses half a pair, carries pkce/resource', () => {
     vi.spyOn(console, 'warn').mockImplementation(() => {});
     const declare = (oauth: unknown) =>
-      descriptorsFromMcpJson(
+      fromMcpJson(
         'GTM',
         JSON.stringify({ mcpServers: { vendor: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),
         JSON.stringify({
@@ -262,9 +267,9 @@ describe('descriptorsFromMcpJson', () => {
 
   it('yields nothing for an unparsable file, quietly for an absent extensions block', () => {
     vi.spyOn(console, 'warn').mockImplementation(() => {});
-    expect(descriptorsFromMcpJson('GTM', '{ not json', null)).toEqual([]);
+    expect(fromMcpJson('GTM', '{ not json', null)).toEqual([]);
     expect(
-      descriptorsFromMcpJson('GTM', JSON.stringify({ mcpServers: {} }), '{ also not json'),
+      fromMcpJson('GTM', JSON.stringify({ mcpServers: {} }), '{ also not json'),
     ).toEqual([]);
   });
 });

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

@@ -9,6 +9,7 @@ import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { IToolManualService, ToolManualSummary } from '../tool-manuals.contract.js';
 import { McpServerEditService } from '../mcp-server-edit.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB = 'knowledge-base';
 const USER: AuthUser = { id: 'u-1', email: 'ali@example.com', name: 'Ali' } as AuthUser;
@@ -77,7 +78,7 @@ beforeEach(async () => {
     }),
   } as unknown as IToolManualService;
 
-  svc = new McpServerEditService(workspaceService, commits, accessControl, toolManuals, KB, new NodeFs());
+  svc = new McpServerEditService(workspaceService, commits, accessControl, toolManuals, testKbContext({ kbDirName: KB }), new NodeFs());
 });
 
 afterEach(async () => {

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

@@ -5,6 +5,7 @@ import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { IToolManualService, ToolManualSummary } from '../tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The half of the tool catalog that is NOT on the default branch.
@@ -93,7 +94,7 @@ function harness(opts: {
     listChangeRequests: async () => opts.crs,
   } as unknown as IWorkflowService;
 
-  return new PendingToolsService(workspaceService, accessControl, toolManuals, workflow);
+  return new PendingToolsService(workspaceService, accessControl, toolManuals, workflow, testKbContext());
 }
 
 const ADMIN_WRITES = { [TOOL_PATH]: [ADMIN] };
@@ -370,6 +371,7 @@ describe('PendingToolsService', () => {
       {} as unknown as IAccessControl,
       { listAllSummaries: async () => [] } as unknown as IToolManualService,
       workflow,
+      testKbContext(),
     );
     await expect(svc.listPendingTools(AUTHOR)).resolves.toEqual([]);
   });
@@ -384,6 +386,7 @@ describe('PendingToolsService', () => {
         },
       } as unknown as IToolManualService,
       { listChangeRequests: async () => [cr()] } as unknown as IWorkflowService,
+      testKbContext(),
     );
     await expect(svc.listPendingTools(AUTHOR)).resolves.toEqual([]);
   });

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

@@ -12,6 +12,7 @@ import type { IPluginIndexService, PluginCatalogEntry } from '../../plugins/plug
 import type { PluginSource, Discovery } from '../../plugins/discovery/plugin-source.js';
 import type { IToolManualService, ToolManualSummary } from '../tool-manuals.contract.js';
 import { ToolDeleteError, ToolDeleteService } from '../tool-delete.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * Deleting one tool, over a real temp KB: the two shapes a tool comes in (a
@@ -147,7 +148,7 @@ function build(
     pluginIndex,
     opts.source ?? discovery([]),
     vault as never,
-    KB,
+    testKbContext({ kbDirName: KB }),
     new NodeFs(),
   );
 }

package/src/modules/tool-manuals/__tests__/tool-manuals.archive.route.test.ts

@@ -11,6 +11,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { IToolManualService } from '../tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * `GET /agent/plugins/:folder/archive` — error taxonomy of the plugin-folder
@@ -47,7 +48,7 @@ async function baseUrl(pluginIndex?: { catalog(): Promise<{ name: string; folder
       {} as unknown as IToolManualService,
       manualAuth,
       async () => 'ali@example.com',
-      { workspaceService, accessControl, kbDirName: KB, disk: new NodeFs(), pluginIndex: pluginIndex as never },
+      { workspaceService, accessControl, kb: testKbContext({ kbDirName: KB }), disk: new NodeFs(), pluginIndex: pluginIndex as never },
     ),
   );
   httpServer = await new Promise<HttpServer>((resolve) => {

package/src/modules/tool-manuals/__tests__/tool-manuals.cli.test.ts

@@ -15,6 +15,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { utcpNamespacePrefix } from '../../../shared/utcp-namespace.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB_DIR = 'knowledge-base';
 const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
@@ -146,7 +147,7 @@ describe('a shell `.tool` in a workspace', () => {
   afterEach(() => rm(root, { recursive: true, force: true }));
 
   test('is listed to local consumers and withheld from remote ones', async () => {
-    const svc = new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk));
+    const svc = new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
     // `list_local_tools` names it, so the local server knows to materialize it.
     expect(await svc.listLocalOnly('user@x.eu')).toEqual([{ slug: 'git', name: 'git', path: 'Plugins/git.tool' }]);
     // The hosted proxy's manual set excludes it entirely.
@@ -157,7 +158,7 @@ describe('a shell `.tool` in a workspace', () => {
   test('its embedded cli tools survive manual serialization', async () => {
     // The whole point of registering the serializer: without it the manual body
     // fails validation and the local server gets nothing to run.
-    const svc = new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk));
+    const svc = new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
     const manual = await svc.resolveInlineManual('user@x.eu', 'git');
     expect(manual).not.toBeNull();
     const tools = (manual as { tools: { name: string; tool_call_template: { call_template_type: string } }[] }).tools;
@@ -206,7 +207,7 @@ describe('manual namespaces are unique, not merely manual names', () => {
   }
 
   const names = async (): Promise<string[]> =>
-    (await new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk)).listAllSummaries()).map((m) => m.name).sort();
+    (await new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR }))).listAllSummaries()).map((m) => m.name).sort();
 
   it('keeps two manuals whose namespaces genuinely differ', async () => {
     // Underscore-doubling is injective, so `a_b` (a__b_) and `a__b` (a____b_)
@@ -243,7 +244,7 @@ describe('manual namespaces are unique, not merely manual names', () => {
     await writeMcpServer('Vendor', 'a-b');
     await writeTool('a.tool', 'a_b');
     await writeTool('c.tool', 'other');
-    const kept = await new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk)).listAllSummaries();
+    const kept = await new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR }))).listAllSummaries();
     const namespaces = kept.map((m) => utcpNamespacePrefix(m.name));
     expect(new Set(namespaces).size).toBe(namespaces.length);
   });

package/src/modules/tool-manuals/__tests__/tool-manuals.detail.route.test.ts

@@ -16,6 +16,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { IToolManualService, ToolManualDetail } from '../tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * `GET /api/tools/:slug` — the browser tool page's detail read. Two halves:
@@ -165,7 +166,7 @@ describe('ToolManualService.getDetail — capabilities + access', () => {
     canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
   } as unknown as IAccessControl;
 
-  const svc = (access: IAccessControl = allowAll) => new ToolManualService(workspaceService, access, KB_DIR, disk, new KbPluginSource(disk));
+  const svc = (access: IAccessControl = allowAll) => new ToolManualService(workspaceService, access, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
 
   /** Write one `.tool` into a fresh temp KB and return the service over it. */
   async function withTool(file: string, content: string): Promise<void> {

package/src/modules/tool-manuals/__tests__/tool-manuals.invalid.routes.test.ts

@@ -13,6 +13,7 @@ import { ToolManualService } from '../tool-manuals.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * THE TWO HTTP SURFACES, over a real catalog.
@@ -80,9 +81,9 @@ async function baseUrlAs(email: string | undefined): Promise<{ base: string; ser
   const service = new ToolManualService(
     workspaceService,
     accessControl,
-    KB_DIR,
+    testKbContext({ kbDirName: KB_DIR }),
     disk,
-    new KbPluginSource(disk),
+    new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })),
     () => clock,
   );
   const app = express();
@@ -98,6 +99,7 @@ async function baseUrlAs(email: string | undefined): Promise<{ base: string; ser
   app.use(
     '/api',
     createSecretsVaultRoutes({
+      kb: testKbContext({ kbDirName: KB_DIR }),
       secretsVault: { statusFor: async () => [] } as unknown as Parameters<
         typeof createSecretsVaultRoutes
       >[0]['secretsVault'],