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

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

@@ -3,18 +3,13 @@ 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,
-} from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { spliceGrant } from '../access-model/access-splice.js';
+import { folderTarget } from '../access/access-requests.contract.js';
+import { AccessRequestsService } from '../access/access-requests.service.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';
@@ -29,13 +24,11 @@ import type { ISkillService } from './skills.contract.js';
  *
  * Why it exists: linking a skill into a plugin needs write on the skill's
  * rules (the link grants the plugin's principal there), and a plugin manager
- * often has no say over a skill some other scope owns. The request is a plain
- * change request whose branch splices `write: <requester>` into the skill
- * folder's `access.md`; the skill's editors see its proposals and accept
- * through the ordinary grant path, and it retires itself once the default
- * branch carries the grant (`JoinRequestsService`, keyed on the skill FOLDER
- * path rather than a plugin name — the branch-name convention takes any
- * exact string).
+ * often has no say over a skill some other scope owns. The request is opened
+ * by the shared `AccessRequestsService` — the same one the Manage access
+ * dialog's Request access uses — keyed on the skill FOLDER path, so this
+ * button and a Can edit request on that same folder are ONE request, shown in
+ * the skill page's banner and in the folder's dialog alike.
  *
  * Fail-closed like the skill catalog: a skill the caller cannot read answers
  * as unknown, and the editors' listing answers `[]` to anyone else.
@@ -46,13 +39,22 @@ 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 router = express.Router();
-  const wsId = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  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,
+  });
 
   /** The skill the caller may read, by name — or null after answering 404. */
   async function readableSkill(
@@ -82,65 +84,13 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(409).json({ error: 'You can already edit this skill', kind: 'already-writable' });
         return;
       }
-      const branch = joinBranchFor(user.email, folder);
-      // FRESH: a repeated click must find the request the previous one opened,
-      // and the cached listing can trail it — a miss here would send the
-      // retry into a duplicate refusal.
-      const existing = (await workflow.listChangeRequestsAuthoredBy(user.email, { fresh: true })).find(
-        (cr) => cr.state === 'open' && cr.branch === branch,
-      );
-      if (existing) {
-        res.json({ ok: true, number: existing.number });
-        return;
-      }
-      // The branch may already exist (a request listed as closed, a retry
-      // after a failed open). Existence is PROBED, before and — if creation
-      // fails — after: the race shows up as "already exists" locally or as a
-      // rejected push when origin got there first, and a message is not a
-      // contract. A branch that is there is proceeded against; anything else
-      // is a real failure, and a proposal on a branch that was not made would
-      // be worse than the error. STRICT: the list proves absence, and a
-      // listing that could not fetch proves nothing — it throws instead of
-      // serving refs from before the branch was made (or deleted).
-      const branchExists = async () =>
-        (await workflow.listBranches(wsId(), { freshFetch: true, strictFetch: true })).some(
-          (b) => b.name === branch,
-        );
-      if (!(await branchExists())) {
-        try {
-          await workflow.createBranch(wsId(), branch, DEFAULT_BRANCH);
-        } catch (err) {
-          if (!(await branchExists())) throw err;
-        }
-      }
-      const ws = await workspaceService.getOrCreateForBranch(branch);
-      const accessPath = `${kbDirName}/${rulesOf(folder)}`;
-      // Only a PROVEN absence reads as "no rules yet": any other failure must
-      // not be turned into an empty file that a splice then overwrites.
-      const current = await workspaceService.readFile(ws.id, accessPath).catch((err: unknown) => {
-        if (!isAbsence(err)) throw err;
-        return '';
-      });
-      const spliced = spliceGrant(
-        current,
-        'write',
-        { kind: 'user', email: user.email, displayName: user.name },
-        { target: 'folder' },
-      );
-      if (spliced.changed) {
-        await workspaceService.writeFile(ws.id, accessPath, spliced.text);
-        await workflow.commitChanges(ws.id, user, `Request write access to ${name}`);
-      }
-      const detail = await workflow.openChangeRequest(ws.id, user, {
-        sourceBranch: branch,
-        targetBranch: DEFAULT_BRANCH,
-        title: `Access request: ${name}`,
-        description:
-          `${user.name} asked to edit the skill ${name}. An editor of the skill accepts by ` +
-          `granting the access this branch proposes; the request closes itself once ` +
-          `every proposal has landed.`,
+      const { number } = await requests.open({
+        user,
+        target: folderTarget(folder),
+        itemName: name,
+        level: 'write',
       });
-      res.json({ ok: true, number: detail.number });
+      res.json({ ok: true, number });
     } catch (err) {
       if (err instanceof WorkflowDomainError) {
         res.status(err.status).json(domainErrorBody(err));
@@ -171,7 +121,7 @@ export function createSkillAccessRequestRoutes(deps: {
       const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
       if (!ctx) return;
       const crs = await workflow.listChangeRequests();
-      res.json({ requests: await joinRequests.list(ctx.folder, ctx.folder, crs, ctx.user) });
+      res.json({ requests: await joinRequests.list(ctx.folder, folderTarget(ctx.folder), crs, ctx.user) });
     } catch (err) {
       log.error('failed to list access requests:', { err });
       res.status(500).json({ error: 'Failed to list access requests' });
@@ -192,7 +142,7 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(404).json({ error: 'Not found' });
         return;
       }
-      res.json({ closed: await joinRequests.reconcile(ctx.folder, ctx.folder, cr, ctx.user) });
+      res.json({ closed: await joinRequests.reconcile(ctx.folder, folderTarget(ctx.folder), cr, ctx.user) });
     } catch (err) {
       log.error('failed to reconcile an access request:', { err });
       res.status(500).json({ error: 'Failed to reconcile the request' });

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-helpers/tool-context.ts

@@ -12,6 +12,7 @@ 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';
 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';
@@ -77,6 +78,20 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
     const { loadActiveGroups } = deps;
     const fsCache = new Map<string, LocalFilesystem>();
     const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
+      // THE choke point: every knowledge-base tool resolves its workspace
+      // through here, and a `call_tool_chain` call reaches the very same route
+      // over loopback — so refusing a branch-less call here refuses it on both
+      // paths at once, with no per-tool guard to keep in step.
+      //
+      // Before ANY workspace work, because both things downstream do with this
+      // value are wrong when it is absent: `getOrCreateForUser` defaults a
+      // missing branch to the deployment's default (protected) branch, so an
+      // omitted argument would silently act on `main`; and a present-but-absent
+      // value like the string "undefined" goes to `workspaceIdForBranch`, which
+      // makes it a workspace directory of that name and then tries to clone a
+      // branch nobody ever pushed. Failing closed here means no workspace is
+      // created and no clone is attempted.
+      assertBranchProvided(branch);
       const cached = fsCache.get(branch);
       if (cached) return cached;
       const ws = await deps.workspaceService.getOrCreateForUser(user, branch);

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);
   });