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

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-auth/__tests__/external-api-key.service.test.ts

@@ -149,6 +149,7 @@ describe('ExternalApiKeyService', () => {
         lastUsedAt: null,
         revokedAt: null,
         revokedBy: null,
+        deletedAt: null,
       });
     });
 
@@ -303,6 +304,7 @@ describe('ExternalApiKeyService', () => {
         lastUsedAt: rows[0].lastUsedAt!.getTime(),
         revokedAt: null,
         revokedBy: null,
+        deletedAt: null,
       });
       expect(summaries[1].revokedAt).toBe(rows[1].revokedAt!.getTime());
       // sanity-check that ordering was requested (we can't introspect the
@@ -333,6 +335,7 @@ describe('ExternalApiKeyService', () => {
           lastUsedAt: aliceKey.lastUsedAt!.getTime(),
           revokedAt: null,
           revokedBy: null,
+          deletedAt: null,
           user: { id: 'u-alice', email: 'alice@example.com', name: 'Alice' },
         },
         {
@@ -343,6 +346,7 @@ describe('ExternalApiKeyService', () => {
           lastUsedAt: null,
           revokedAt: bobKey.revokedAt!.getTime(),
           revokedBy: null,
+          deletedAt: null,
           user: { id: 'u-bob', email: 'bob@example.com', name: 'Bob' },
         },
       ]);
@@ -439,9 +443,9 @@ describe('ExternalApiKeyService', () => {
   });
 
   describe('remove', () => {
-    it('validates then deletes the key (dependents cascade at the DB layer)', async () => {
-      // Queue: SELECT finds a revoked row; then the key delete consumes one.
-      const { db } = makeFakeDb([
+    it('validates then marks the key deleted — the row stays, for the Audit log', async () => {
+      // Queue: SELECT finds a revoked row; then the marking update consumes one.
+      const { db, calls } = makeFakeDb([
         [{ revokedAt: new Date('2026-02-01T00:00:00Z') }],
         undefined,
       ]);
@@ -449,12 +453,29 @@ describe('ExternalApiKeyService', () => {
 
       await service.remove('tok-1', 'user-1');
 
-      // Validation SELECT first, then ONE delete of the key row. Dependent
-      // rows (e.g. llm_usage metering) are removed by ON DELETE CASCADE —
-      // this service must not know those tables exist.
+      // Validation SELECT first, then ONE update of the key row and never a
+      // delete: the Audit log's events hang off this row, and a key's owner
+      // deleting it must not erase what it did. Only a revoked, not-yet-
+      // deleted row of the owner's is marked.
       expect((db as any).select).toHaveBeenCalledTimes(1);
-      expect((db as any).delete).toHaveBeenCalledTimes(1);
-      expect((db as any).delete).toHaveBeenCalledWith(externalApiKeys);
+      expect((db as any).delete).not.toHaveBeenCalled();
+      expect((db as any).update).toHaveBeenCalledTimes(1);
+      expect((db as any).update).toHaveBeenCalledWith(externalApiKeys);
+      expect(calls.set[0]![0].deletedAt).toBeInstanceOf(Date);
+      const mark = renderSql(calls.where[1]![0]).sql;
+      expect(mark).toMatch(/"api_tokens"."user_id" = \$2/);
+      expect(mark).toMatch(/"api_tokens"."revoked_at" is not null/);
+      expect(mark).toMatch(/"api_tokens"."deleted_at" is null/);
+    });
+
+    it('treats an already-deleted key as absent for its owner', async () => {
+      // The validation SELECT carries the not-deleted filter, so a deleted
+      // row answers nothing — and nothing is marked twice.
+      const { db, calls } = makeFakeDb([[]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+      await expect(service.remove('tok-1', 'user-1')).rejects.toBeInstanceOf(TokenNotFoundError);
+      expect(renderSql(calls.where[0]![0]).sql).toMatch(/"api_tokens"."deleted_at" is null/);
+      expect((db as any).update).not.toHaveBeenCalled();
     });
 
     it('throws TokenStillActiveError when the token exists but was never disconnected', async () => {

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

@@ -22,6 +22,12 @@ describe('InternalTokenService', () => {
     expect(svc.verify(token)).toEqual({ userId: 'user-A', externalProxy: true });
   });
 
+  it('round-trips the connectionId claim (the agent behind an exchanged OAuth grant)', () => {
+    const svc = new InternalTokenService({ secret: 'test-secret' });
+    const token = svc.mint({ userId: 'user-A', externalProxy: true, connectionId: 'conn-1' });
+    expect(svc.verify(token)).toEqual({ userId: 'user-A', externalProxy: true, connectionId: 'conn-1' });
+  });
+
   it('round-trips the focusedBranch claim (the in-process agent workspace branch)', () => {
     const svc = new InternalTokenService({ secret: 'test-secret' });
     const token = svc.mint({ userId: 'user-A', sessionId: 'run-1', focusedBranch: 'main' });

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

@@ -37,6 +37,12 @@ export interface ExternalApiKeySummary {
    * before this was recorded, which read as the owner's doing).
    */
   revokedBy: RevokedBy | null;
+  /**
+   * When the owner deleted the key for good from their own pages. Such a
+   * key is absent from the owner's listings and shown to admins as deleted;
+   * its row stays so the Audit log's events keep their principal.
+   */
+  deletedAt: number | null;
 }
 
 /** Who revoked a key: its owner, or an admin acting across the deployment. */
@@ -137,6 +143,13 @@ export interface IExternalApiKeyService {
   /** Active + revoked tokens for the user, newest-first. */
   listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
 
+  /**
+   * The account a key belongs to, live or revoked, or null when no such key
+   * exists. The ownership check behind a per-key read or revoke that is
+   * offered to owners and admins alike (the Audit log's).
+   */
+  ownerOf(id: string): Promise<string | null>;
+
   /**
    * Mark a token revoked. Idempotent — revoking an already-revoked token
    * is a no-op (the row's `revokedAt` is not overwritten). Throws
@@ -161,11 +174,15 @@ export interface IExternalApiKeyService {
   revokeAny(id: string): Promise<void>;
 
   /**
-   * Permanently delete a token row, dropping its audit trail. Only permitted
-   * on an already-revoked token — an active key must be disconnected first,
-   * so a live agent's access is never yanked by a single click. Throws
-   * TokenNotFoundError if the token doesn't belong to the user, and
-   * TokenStillActiveError if it hasn't been revoked yet.
+   * Delete a token for good, from the owner's point of view: it leaves their
+   * listings and can never be used or reconnected. The row itself stays,
+   * marked deleted, so the Audit log keeps the key's events under their
+   * principal — a log its subject could erase would not be one. Only
+   * permitted on an already-revoked token — an active key must be
+   * disconnected first, so a live agent's access is never yanked by a single
+   * click. Throws TokenNotFoundError if the token doesn't belong to the user
+   * (or is already deleted), and TokenStillActiveError if it hasn't been
+   * revoked yet.
    */
   remove(id: string, userId: string): Promise<void>;
 }

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

@@ -144,14 +144,25 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
   }
 
   async listForUser(userId: string): Promise<ExternalApiKeySummary[]> {
+    // A key the owner deleted for good is gone from THEIR listings — that is
+    // what the deletion means to them; the row lives on for the Audit log.
     const rows = await this.db
       .select()
       .from(externalApiKeys)
-      .where(eq(externalApiKeys.userId, userId))
+      .where(and(eq(externalApiKeys.userId, userId), isNull(externalApiKeys.deletedAt)))
       .orderBy(desc(externalApiKeys.createdAt));
     return rows.map(toSummary);
   }
 
+  async ownerOf(id: string): Promise<string | null> {
+    const [row] = await this.db
+      .select({ userId: externalApiKeys.userId })
+      .from(externalApiKeys)
+      .where(eq(externalApiKeys.id, id))
+      .limit(1);
+    return row?.userId ?? null;
+  }
+
   async listForDeployment(): Promise<AdminExternalApiKeySummary[]> {
     // Owner joined in so the admin overview is one round-trip; ordered by
     // owner email so per-account grouping is a linear pass, newest key
@@ -219,14 +230,16 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
   }
 
   async remove(id: string, userId: string): Promise<void> {
-    // Only revoked rows may be hard-deleted — deleting an active key would
+    // Only revoked rows may be deleted — deleting an active key would
     // silently cut off a live agent. Scope by userId so a user can only
     // delete their own tokens. Validate first (so we can return a precise
-    // not-found vs still-active error), then delete inside a transaction.
+    // not-found vs still-active error), then mark the row deleted.
     const [existing] = await this.db
       .select({ revokedAt: externalApiKeys.revokedAt })
       .from(externalApiKeys)
-      .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+      .where(
+        and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId), isNull(externalApiKeys.deletedAt)),
+      )
       .limit(1);
     if (!existing) {
       throw new TokenNotFoundError();
@@ -236,16 +249,19 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       throw new TokenStillActiveError();
     }
 
-    // Dependents (e.g. the enterprise LLM-usage metering rows) hang off this
-    // row via ON DELETE CASCADE foreign keys, so a bare delete takes any audit
-    // trail with it — this service doesn't have to know those tables exist.
+    // A deletion in name: the row stays, marked, because the Audit log's
+    // events hang off it and the trail must outlive the key's owner's wish
+    // to be rid of it. The key was revoked already, so nothing can use it;
+    // deleting hides it from the owner and tells an admin it was deleted.
     await this.db
-      .delete(externalApiKeys)
+      .update(externalApiKeys)
+      .set({ deletedAt: new Date() })
       .where(
         and(
           eq(externalApiKeys.id, id),
           eq(externalApiKeys.userId, userId),
           isNotNull(externalApiKeys.revokedAt),
+          isNull(externalApiKeys.deletedAt),
         ),
       );
   }
@@ -271,5 +287,6 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
     lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
     revokedBy: (row.revokedBy as RevokedBy | null) ?? null,
+    deletedAt: row.deletedAt ? row.deletedAt.getTime() : null,
   };
 }

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

@@ -37,6 +37,16 @@ export interface InternalTokenClaim {
    * expected to carry `sessionId` on the tool body, not in the token.
    */
   externalProxy?: boolean;
+  /**
+   * The agent connection (`agent_connections.id`) an external-proxy token
+   * stands in for. The LOCAL MCP server swaps its OAuth grant for one of these
+   * at `/api/mcp/local-token` and presents it everywhere the grant would have
+   * gone, so without this claim every call it makes would arrive with a user
+   * and no agent — unattributable in the Audit log. Carried, never decided:
+   * the exchange copies it from the verified grant. Absent on every other
+   * internal token.
+   */
+  connectionId?: string;
 }
 
 interface SignedPayload extends InternalTokenClaim {
@@ -137,6 +147,7 @@ export class InternalTokenService {
       ...(typeof payload.sessionId === 'string' ? { sessionId: payload.sessionId } : {}),
       ...(typeof payload.focusedBranch === 'string' ? { focusedBranch: payload.focusedBranch } : {}),
       ...(payload.externalProxy === true ? { externalProxy: true } : {}),
+      ...(typeof payload.connectionId === 'string' ? { connectionId: payload.connectionId } : {}),
     };
   }
 

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

@@ -34,6 +34,14 @@ export interface ToolAuth {
    * never carries it and must name the branch explicitly.
    */
   focusedBranch?: string;
+  /**
+   * The agent connection an `externalProxy` token stands in for — the local
+   * server's exchanged grant names one (see `InternalTokenClaim.connectionId`).
+   * Only that grant carries it: the hosted proxy's own loopback tokens do
+   * not, and a connection key has a `tokenId` instead. What the REST audit
+   * recorder attributes a direct tool call to.
+   */
+  connectionId?: 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';
 }
@@ -129,7 +137,15 @@ export function createTokenVerifier(
       const claim = internalTokenService.verify(token);
       if (!claim) return { ok: false, status: 401, message: 'Invalid or expired internal token' };
       return claim.externalProxy
-        ? { ok: true, auth: { source: 'external', userId: claim.userId, scope: 'write' } }
+        ? {
+            ok: true,
+            auth: {
+              source: 'external',
+              userId: claim.userId,
+              ...(claim.connectionId ? { connectionId: claim.connectionId } : {}),
+              scope: 'write',
+            },
+          }
         : { ok: true, auth: { source: 'internal', userId: claim.userId, sessionId: claim.sessionId, focusedBranch: claim.focusedBranch, scope: 'write' } };
     }
 

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([]);
   });