@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/src/modules/settings/setup.routes.ts

@@ -30,9 +30,40 @@ const execFileAsync = promisify(execFile);
 export function createSetupRoutes(
   settings: DeploymentSettingsService,
   adminAccess: IAdminAccessService,
+  /**
+   * The KB startup phase, invoked at its SECOND quiet moment: the save that
+   * completes first-time setup. The app is gated shut until exactly then
+   * (`isComplete`), so no session can be holding a working clone the phase
+   * would race.
+   */
+  kbStartupRunner: { runAll(): Promise<void> },
 ): express.Router {
   const router = express.Router();
 
+  /**
+   * Whether the last setup-time run of the KB startup phase FAILED. While
+   * true the deployment stays GATED: the settings are saved but the KB was
+   * never initialized, and reporting setup complete would open the app over
+   * an unmaintained (possibly unseeded) knowledge base. Saving the setup
+   * form again retries the phase; a server restart retries it at boot; a
+   * success clears the flag. Per-process state, like the gate itself.
+   */
+  let kbInitFailed = false;
+  /** The failure's message, surfaced to the ADMIN on the status endpoint. */
+  let kbInitError: string | null = null;
+  /**
+   * The setup-time run currently executing, if any. Its jobs: (a) keeping the
+   * status gate SHUT while a run executes (the settings read complete the
+   * moment they save, but the phase is still mutating branch trees — no
+   * workspace request may start yet), and (b) defense in depth via the `??=`
+   * at the run site, should a second invoker ever appear. It is NOT what
+   * serializes saves — the `saveTurn` chain below runs handlers strictly one
+   * at a time, phase included, so no second run can start while one executes.
+   */
+  let kbInitInFlight: Promise<void> | null = null;
+  /** The app-gate answer: settings complete AND the KB phase settled clean. */
+  const kbReady = () => isComplete(settings) && !kbInitFailed && kbInitInFlight === null;
+
   const requireAdmin: express.RequestHandler = async (req, res, next) => {
     if (!(await adminAccess.isAdmin(req.userEmail))) {
       res.status(403).json({ error: 'Admins only' });
@@ -51,25 +82,51 @@ export function createSetupRoutes(
    * secret's value.
    */
   router.get('/setup/status', async (req, res) => {
-    const complete = isComplete(settings);
+    // A failed OR still-running setup-time KB initialization keeps setup
+    // INCOMPLETE: the frontend gates the app on this answer, and opening it
+    // over an uninitialized (or mid-mutation) KB would be worse than keeping
+    // the setup screen up.
+    //
+    // `kbReady()` is read fresh AFTER the admin check, immediately before
+    // building each response: the check awaits, a completion save can start
+    // the phase during that await, and a snapshot taken before it would
+    // resurrect a pre-phase `true` — opening the gate mid-mutation.
     if (!(await adminAccess.isAdmin(req.userEmail))) {
-      res.json({ complete, isAdmin: false });
+      res.json({ complete: kbReady(), isAdmin: false });
       return;
     }
     res.json({
-      complete,
+      complete: kbReady(),
       awaitingRestart: awaitingRestart(settings),
       isAdmin: true,
       settings: settings.describe(),
+      ...(kbInitFailed ? { kbInitError } : {}),
     });
   });
 
+  /**
+   * Setup saves run strictly ONE AT A TIME, phase included: `settings.save`
+   * updates the live cache write by write, and the completing save runs the
+   * KB startup phase, which reads its configuration through live getters —
+   * a save interleaving with either would hand half-updated state to the
+   * other. A plain promise chain is enough: saves are a setup-screen rarity,
+   * not a hot path, and a save arriving mid-run simply waits the previous
+   * save (and its phase) out before proceeding.
+   */
+  let saveTurn: Promise<unknown> = Promise.resolve();
+
   /**
    * Save settings. Validated and written as ONE batch — a repository URL
    * stored without the token that reads it is a deployment that fails at its
    * first clone, so a partial write is never better than none.
    */
   router.post('/setup/settings', requireAdmin, async (req, res) => {
+    const turn = saveTurn.then(() => handleSave(req, res));
+    saveTurn = turn.catch(() => {});
+    await turn;
+  });
+
+  async function handleSave(req: express.Request, res: express.Response): Promise<void> {
     const body = (req.body ?? {}) as { settings?: Record<string, unknown> };
     const entries: Record<string, string> = {};
     for (const [key, value] of Object.entries(body.settings ?? {})) {
@@ -80,6 +137,11 @@ export function createSetupRoutes(
       entries[key] = value;
     }
     try {
+      // Completion is a TRANSITION, so it is measured BEFORE the save: the
+      // save that flips it false→true — whichever field arrives last — is the
+      // one that must run the KB startup phase, regardless of which save
+      // configured the branch model.
+      const wasComplete = isComplete(settings);
       const { restartRequired } = await settings.save(entries, req.userId ?? null);
       /**
        * Apply the branch model to THIS process, so pressing Save finishes
@@ -102,10 +164,55 @@ export function createSetupRoutes(
         };
         if (!validateBranchModel(model)) configureBranchModel(model);
       }
+      /**
+       * The save that COMPLETES setup is the KB startup phase's SECOND quiet
+       * moment (the other is boot): the app was gated shut until this very
+       * response, so the trees are provably quiet. Run the phase now —
+       * seeding the remote, scaffolding and migrating every branch — so the
+       * first workspace request that follows finds a maintained KB.
+       *
+       * Runs on the false→true completion transition — including when the
+       * branch model was configured by an EARLIER save and the repository
+       * URL arrives on a later one — and again on any save while a previous
+       * setup-time run stands failed (`kbInitFailed`), so saving the form is
+       * the retry. Never on a re-save of a complete, healthy setup: with the
+       * gate open, sessions may be live and that is no longer a quiet moment.
+       */
+      if ((!wasComplete || kbInitFailed) && isComplete(settings)) {
+        try {
+          // One run at a time. The save chain already serializes handlers
+          // whole, so no second run can start while one executes; the `??=`
+          // is defense in depth should another invoker ever appear.
+          kbInitInFlight ??= kbStartupRunner.runAll();
+          await kbInitInFlight;
+          // Under KB_SAFE_BOOT a run that abandoned the phase still resolves
+          // and opens the gate DELIBERATELY — booting unmaintained so the
+          // operator can get in and fix things is exactly what the
+          // break-glass is for.
+          kbInitFailed = false;
+          kbInitError = null;
+        } catch (initErr) {
+          // The settings ARE saved — only the KB initialization failed. The
+          // deployment stays gated (see the status endpoint) until a retry
+          // succeeds. Logged in full, returned actionable.
+          const msg = initErr instanceof Error ? initErr.message : String(initErr);
+          console.error('[setup] KB initialization failed after setup completed:', msg);
+          kbInitFailed = true;
+          kbInitError = msg;
+          res.status(500).json({
+            error:
+              'Settings saved, but the knowledge base could not be initialized. ' +
+              'Saving the setup form again retries; restarting the server retries too.',
+          });
+          return;
+        } finally {
+          kbInitInFlight = null;
+        }
+      }
       res.json({
         ok: true,
         restartRequired,
-        complete: isComplete(settings),
+        complete: kbReady(),
         awaitingRestart: awaitingRestart(settings),
         settings: settings.describe(),
       });
@@ -119,7 +226,7 @@ export function createSetupRoutes(
       console.error('[setup] save failed:', err instanceof Error ? err.message : String(err));
       res.status(500).json({ error: 'Could not save these settings.' });
     }
-  });
+  }
 
   /**
    * Try the credentials against the real remote, BEFORE anything is saved.

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

@@ -40,7 +40,7 @@ function cr(over: Partial<ChangeRequest> = {}): ChangeRequest {
     base: 'main',
     state: 'open',
     createdAt: '2026-08-06T09:00:00.000Z',
-    touchedNodePaths: ['Groups/Engineering/weekly-newsletter/SKILL.md'],
+    touchedNodePaths: ['Plugins/Engineering/weekly-newsletter/SKILL.md'],
     review: { approvals: 0, changesRequested: 0, pendingLogins: [] },
     url: '/change-requests/7',
     ...over,
@@ -56,7 +56,7 @@ function harness(opts: {
   writers?: Record<string, string[]>;
 }) {
   const branchFiles = opts.branchFiles ?? {
-    'agent/weekly-newsletter:Groups/Engineering/weekly-newsletter/SKILL.md': SKILL_MD,
+    'agent/weekly-newsletter:Plugins/Engineering/weekly-newsletter/SKILL.md': SKILL_MD,
   };
   const workspaceService = {
     ensureRemotesFetched: async () => undefined,
@@ -81,7 +81,7 @@ function harness(opts: {
 }
 
 const ADMIN_WRITES = {
-  'Groups/Engineering/weekly-newsletter/SKILL.md': [ADMIN],
+  'Plugins/Engineering/weekly-newsletter/SKILL.md': [ADMIN],
 };
 
 describe('PendingSkillsService', () => {
@@ -93,7 +93,7 @@ describe('PendingSkillsService', () => {
         name: 'weekly-newsletter',
         description: 'Drafts the Friday newsletter.',
         version: '0.1.0',
-        path: 'Groups/Engineering/weekly-newsletter',
+        path: 'Plugins/Engineering/weekly-newsletter',
         changeRequestNumber: 7,
         branch: 'agent/weekly-newsletter',
         authorName: 'Ali Raza',
@@ -110,7 +110,7 @@ describe('PendingSkillsService', () => {
 
   /**
    * The decision that shapes this surface: a proposal is between its author and
-   * the people who can approve it, and nobody else. A member of the group who
+   * the people who can approve it, and nobody else. A member of the plugin who
    * cannot write the folder is not one of those people.
    */
   test('hides it from everyone else', async () => {
@@ -143,7 +143,7 @@ describe('PendingSkillsService', () => {
         {
           name: 'weekly-newsletter',
           description: 'Drafts the Friday newsletter.',
-          path: 'Groups/Engineering/weekly-newsletter',
+          path: 'Plugins/Engineering/weekly-newsletter',
         },
       ],
       writers: ADMIN_WRITES,
@@ -156,9 +156,9 @@ describe('PendingSkillsService', () => {
       crs: [
         cr({
           touchedNodePaths: [
-            'Groups/Engineering/access.md',
-            'Groups/Engineering/SKILL.md', // a group folder is not a skill
-            'Groups/Engineering/weekly-newsletter/reference.md',
+            'Plugins/Engineering/access.md',
+            'Plugins/Engineering/SKILL.md', // a plugin folder is not a skill
+            'Plugins/Engineering/weekly-newsletter/reference.md',
           ],
         }),
       ],
@@ -185,7 +185,7 @@ describe('PendingSkillsService', () => {
     const svc = harness({
       crs: [cr()],
       branchFiles: {
-        'agent/weekly-newsletter:Groups/Engineering/weekly-newsletter/SKILL.md':
+        'agent/weekly-newsletter:Plugins/Engineering/weekly-newsletter/SKILL.md':
           '---\ndescription: No name declared.\n---\n\n# Body\n',
       },
       writers: ADMIN_WRITES,
@@ -222,17 +222,17 @@ describe('PendingSkillsService', () => {
           number: 3,
           createdAt: '2026-08-01T12:00:00.000Z',
           branch: 'agent/older',
-          touchedNodePaths: ['Groups/Engineering/older/SKILL.md'],
+          touchedNodePaths: ['Plugins/Engineering/older/SKILL.md'],
         }),
       ],
       branchFiles: {
-        'agent/weekly-newsletter:Groups/Engineering/weekly-newsletter/SKILL.md': SKILL_MD,
-        'agent/older:Groups/Engineering/older/SKILL.md':
+        'agent/weekly-newsletter:Plugins/Engineering/weekly-newsletter/SKILL.md': SKILL_MD,
+        'agent/older:Plugins/Engineering/older/SKILL.md':
           '---\nname: older\ndescription: Older.\n---\n',
       },
       writers: {
         ...ADMIN_WRITES,
-        'Groups/Engineering/older/SKILL.md': [ADMIN],
+        'Plugins/Engineering/older/SKILL.md': [ADMIN],
       },
     });
     expect((await svc.listPendingSkills(ADMIN)).map((p) => p.changeRequestNumber)).toEqual([3, 9]);

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

@@ -50,14 +50,14 @@ describe('SkillService', () => {
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
-    const skills = join(root, wsId, KB_DIR, 'Groups');
+    const skills = join(root, wsId, KB_DIR, 'Plugins');
     await mkdir(join(skills, 'rfi', 'scripts'), { recursive: true });
     await writeFile(join(skills, 'rfi', 'SKILL.md'), RFI_SKILL);
     await writeFile(join(skills, 'rfi', 'scripts', 'build_xlsx.py'), 'print("xlsx")\n');
     // A folder with no SKILL.md is not a skill.
     await mkdir(join(skills, 'not-a-skill'), { recursive: true });
     await writeFile(join(skills, 'not-a-skill', 'README.md'), '# nope\n');
-    // A skill nested in a category subfolder (Groups/Development/coding-guidelines).
+    // A skill nested in a category subfolder (Plugins/Development/coding-guidelines).
     await mkdir(join(skills, 'Development', 'coding-guidelines'), { recursive: true });
     await writeFile(
       join(skills, 'Development', 'coding-guidelines', 'SKILL.md'),
@@ -72,7 +72,7 @@ describe('SkillService', () => {
     expect(skills).toHaveLength(2);
     const rfi = skills.find((s) => s.name === 'rfi')!;
     expect(rfi).toBeDefined();
-    expect(rfi.path).toBe('Groups/rfi');
+    expect(rfi.path).toBe('Plugins/rfi');
     expect(rfi.version).toBe('1.4.0');
     expect(rfi.description).not.toBe('|');
     expect(rfi.description).toContain('Specialist RFI responder');
@@ -83,19 +83,19 @@ describe('SkillService', () => {
     const skills = await svc().listSkills();
     const cg = skills.find((s) => s.name === 'coding-guidelines')!;
     expect(cg).toBeDefined();
-    expect(cg.path).toBe('Groups/Development/coding-guidelines');
+    expect(cg.path).toBe('Plugins/Development/coding-guidelines');
     expect(cg.description).toBe('Coding guidelines.');
 
     const res = await svc().getSkill('user@x.eu', 'coding-guidelines');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'skill') {
-      expect(res.skill.path).toBe('Groups/Development/coding-guidelines');
+      expect(res.skill.path).toBe('Plugins/Development/coding-guidelines');
       expect(res.skill.body).toContain('# Guidelines');
     }
   });
 
   test('refuses a colliding id (no auto-suffix) — the shared dedup rule', async () => {
-    const skills = join(root, wsId, KB_DIR, 'Groups');
+    const skills = join(root, wsId, KB_DIR, 'Plugins');
     // Two skills resolve to the same id `dup` (no frontmatter id/name → folder name).
     await mkdir(join(skills, 'Zeta', 'dup'), { recursive: true });
     await writeFile(join(skills, 'Zeta', 'dup', 'SKILL.md'), '---\ndescription: zeta dup\n---\n\n# Z\n');
@@ -104,28 +104,28 @@ describe('SkillService', () => {
 
     const list = await svc().listSkills();
     // Only the first (smallest path) survives; the duplicate is dropped, not suffixed.
-    expect(list.filter((s) => s.name === 'dup').map((s) => s.path)).toEqual(['Groups/Alpha/dup']);
+    expect(list.filter((s) => s.name === 'dup').map((s) => s.path)).toEqual(['Plugins/Alpha/dup']);
     expect(list.find((s) => s.name === 'dup2')).toBeUndefined();
 
     const a = await svc().getSkill('user@x.eu', 'dup');
-    expect(a.ok && a.kind === 'skill' && a.skill.path).toBe('Groups/Alpha/dup');
+    expect(a.ok && a.kind === 'skill' && a.skill.path).toBe('Plugins/Alpha/dup');
   });
 
   test('frontmatter `id`/`name` overrides the folder name for identity', async () => {
-    const skills = join(root, wsId, KB_DIR, 'Groups');
+    const skills = join(root, wsId, KB_DIR, 'Plugins');
     await mkdir(join(skills, 'folderx'), { recursive: true });
     await writeFile(join(skills, 'folderx', 'SKILL.md'), '---\nid: my_skill\ndescription: d\n---\n\n# X\n');
     const list = await svc().listSkills();
-    expect(list.find((s) => s.name === 'my_skill')?.path).toBe('Groups/folderx');
+    expect(list.find((s) => s.name === 'my_skill')?.path).toBe('Plugins/folderx');
   });
 
   test('getSkill returns body, folder path, files and allowed-tools', async () => {
     const res = await svc().getSkill('user@x.eu', 'rfi');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'skill') {
-      expect(res.skill.path).toBe('Groups/rfi');
+      expect(res.skill.path).toBe('Plugins/rfi');
       expect(res.skill.body).toContain('# /rfi: Specialist RFI Responder');
-      expect(res.skill.files).toEqual(['Groups/rfi/scripts/build_xlsx.py']);
+      expect(res.skill.files).toEqual(['Plugins/rfi/scripts/build_xlsx.py']);
       expect(res.skill.allowedTools).toEqual(['Bash', 'Read']);
     }
   });
@@ -134,7 +134,7 @@ describe('SkillService', () => {
     const res = await svc().getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py');
     expect(res.ok).toBe(true);
     if (res.ok && res.kind === 'file') {
-      expect(res.file.path).toBe('Groups/rfi/scripts/build_xlsx.py');
+      expect(res.file.path).toBe('Plugins/rfi/scripts/build_xlsx.py');
       expect(res.file.content).toContain('print("xlsx")');
     }
   });

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

@@ -1,6 +1,6 @@
 import {
   DEFAULT_BRANCH,
-  GROUPS_DIR,
+  PLUGINS_DIR,
   type ChangeRequest,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
@@ -27,9 +27,9 @@ const SKILL_DOC = 'SKILL.md';
  *
  * WHO MAY SEE ONE is narrower than who may see the catalog: the author, and
  * whoever could approve it. "Could approve it" is not re-stated here as a
- * group-admin check — it is `canWrite` on the SKILL.md the request would
+ * plugin-admin check — it is `canWrite` on the SKILL.md the request would
  * create. The new folder carries no `access.md` of its own, so that verdict
- * inherits from the group folder, which IS the group's admin; asking the access
+ * inherits from the plugin folder, which IS the plugin's admin; asking the access
  * tree keeps this surface and the merge gate answering with one voice, and it
  * keeps working for skills nested in a category subfolder that carries rules of
  * its own.
@@ -80,7 +80,7 @@ export class PendingSkillsService implements IPendingSkillService {
     const authorHash = hashEmail(email);
 
     // One access load for every candidate. Resolved on the DEFAULT branch —
-    // the tree as it stands is what says who owns the group the skill is
+    // the tree as it stands is what says who owns the plugin the skill is
     // arriving into; the branch's own copy is written by the proposer and must
     // not get a say in who reviews them.
     const writable = await this.accessControl
@@ -148,16 +148,16 @@ export class PendingSkillsService implements IPendingSkillService {
 /**
  * Is this touched path a skill's own SKILL.md?
  *
- * `Groups/<group>/<skill>/SKILL.md` is the shallowest shape, hence four
+ * `Plugins/<plugin>/<skill>/SKILL.md` is the shallowest shape, hence four
  * segments; deeper ones are skills nested in a category subfolder, which the
- * catalog already supports. `Groups/<group>/SKILL.md` is NOT a skill — a group
+ * catalog already supports. `Plugins/<plugin>/SKILL.md` is NOT a skill — a plugin
  * folder is not itself one.
  */
 function isSkillDoc(repoRelPath: string): boolean {
   const segments = repoRelPath.split('/');
   return (
     segments.length >= 4 &&
-    segments[0] === GROUPS_DIR &&
+    segments[0] === PLUGINS_DIR &&
     segments[segments.length - 1] === SKILL_DOC
   );
 }

package/src/modules/skills/skills.contract.ts

@@ -1,5 +1,5 @@
 /**
- * Skills are reusable specialist instructions living under `Groups/<group>/<name>/SKILL.md`
+ * Skills are reusable specialist instructions living under `Plugins/<plugin>/<name>/SKILL.md`
  * in the KB repo. Discovery/loading is pinned to the DEFAULT branch — the catalog
  * is a single global, released set (a skill on a draft isn't discoverable until
  * merged). Progressive disclosure: `listSkills` = name + description (level 1),
@@ -12,7 +12,7 @@ export interface SkillSummary {
   name: string;
   description: string;
   version?: string;
-  /** Repo-root-relative skill folder, e.g. `Groups/Everyone/rfi`. */
+  /** Repo-root-relative skill folder, e.g. `Plugins/Everyone/rfi`. */
   path: string;
 }
 
@@ -21,7 +21,7 @@ export interface Skill extends SkillSummary {
   body: string;
   /** Pre-approved tools from the `allowed-tools` frontmatter, if declared. */
   allowedTools?: string[];
-  /** Repo-root-relative bundled file paths, e.g. `Groups/Everyone/rfi/scripts/build_xlsx.py`. */
+  /** Repo-root-relative bundled file paths, e.g. `Plugins/Everyone/rfi/scripts/build_xlsx.py`. */
   files: string[];
 }
 
@@ -48,7 +48,7 @@ export type GetSkillResult =
  *
  * Who may see one is narrower than who may see the catalog: its author, and
  * whoever could approve it. See `PendingSkillsService` for why that predicate
- * is the access tree's answer rather than a group-admin check spelled out
+ * is the access tree's answer rather than a plugin-admin check spelled out
  * again here.
  */
 export interface PendingSkill extends SkillSummary {

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

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import { parseDocument } from 'yaml';
-import { DEFAULT_BRANCH, GROUPS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../workspace/workspace.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
@@ -103,8 +103,8 @@ export class SkillService implements ISkillService {
   }
 
   private async scanDisk(): Promise<ParsedSkill[]> {
-    // Ensure the default-branch clone exists, then scan its Groups/ dir. Any
-    // failure (no workspace, no Groups/ dir) degrades to an empty catalog — the
+    // Ensure the default-branch clone exists, then scan its Plugins/ dir. Any
+    // failure (no workspace, no Plugins/ dir) degrades to an empty catalog — the
     // manual/tools must never break because skills can't be read.
     let wsId: string;
     try {
@@ -119,7 +119,7 @@ export class SkillService implements ISkillService {
     // tree and treat every folder that directly contains a SKILL.md as a skill;
     // don't descend past it — its inner files are bundled assets, not nested
     // skills. The skill name is the leaf folder name; its path is the full
-    // repo-relative folder (e.g. `Groups/Development/coding-guidelines`).
+    // repo-relative folder (e.g. `Plugins/Development/coding-guidelines`).
     const out: ParsedSkill[] = [];
     const walk = async (dir: string, relFolder: string): Promise<void> => {
       let entries: import('node:fs').Dirent[];
@@ -156,7 +156,7 @@ export class SkillService implements ISkillService {
         await walk(path.join(dir, entry.name), `${relFolder}/${entry.name}`);
       }
     };
-    await walk(path.join(kbRoot, GROUPS_DIR), GROUPS_DIR);
+    await walk(path.join(kbRoot, PLUGINS_DIR), PLUGINS_DIR);
     // A skill's id (frontmatter `id`/`name`, else folder name) is how getSkill()
     // resolves it, so it must be unique. Sort by (name, path) for a deterministic
     // winner, then REFUSE later duplicates via the shared dedup — the same rule

package/src/modules/tool-auth/llm-usage-meter.ts

@@ -1,19 +1,19 @@
-/**
- * Metering view over connection-key LLM usage, consumed by the connection-key
- * management routes (mcp) to show each key's spend against the daily budget.
- * The enterprise LLM proxy's `LlmUsageService` satisfies this structurally; a
- * core-only deployment (no LLM proxy, nothing to meter) passes
- * {@link unmeteredLlmUsage}.
- */
-export interface ILlmUsageMeter {
-  /** Daily per-key token cap shown in the UI, or null when unmetered. */
-  readonly dailyCap: number | null;
-  /** Today's usage per key id, as `{ [tokenId]: tokens }` — missing keys mean 0. */
-  usageForTokens(tokenIds: string[]): Promise<Record<string, number>>;
-}
-
-/** Core default: no proxy, no metering — every key reads as unused/uncapped. */
-export const unmeteredLlmUsage: ILlmUsageMeter = {
-  dailyCap: null,
-  usageForTokens: async () => ({}),
-};
+/**
+ * Metering view over connection-key LLM usage, consumed by the connection-key
+ * management routes (mcp) to show each key's spend against the daily budget.
+ * The enterprise LLM proxy's `LlmUsageService` satisfies this structurally; a
+ * core-only deployment (no LLM proxy, nothing to meter) passes
+ * {@link unmeteredLlmUsage}.
+ */
+export interface ILlmUsageMeter {
+  /** Daily per-key token cap shown in the UI, or null when unmetered. */
+  readonly dailyCap: number | null;
+  /** Today's usage per key id, as `{ [tokenId]: tokens }` — missing keys mean 0. */
+  usageForTokens(tokenIds: string[]): Promise<Record<string, number>>;
+}
+
+/** Core default: no proxy, no metering — every key reads as unused/uncapped. */
+export const unmeteredLlmUsage: ILlmUsageMeter = {
+  dailyCap: null,
+  usageForTokens: async () => ({}),
+};