@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/skills/__tests__/skills.tools.description.test.ts

@@ -0,0 +1,95 @@
+import { callLine } from '@bevel-software/platform-mcp-core';
+import express from 'express';
+import { describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { TOOL_DESCRIPTION_CAP, clientVisibleLength } from '../../tool-registry/description-length.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { registerSkillsTools } from '../skills.tools.js';
+import type { ISkillService, Skill } from '../skills.contract.js';
+
+/**
+ * The two skill tools name the skills the caller may read in their
+ * descriptions. The catalog is the organisation's to grow, and a client cuts
+ * a long description from the END — so the names are the part that gives way,
+ * never the tool's own text, and never an id cut in half.
+ */
+describe('the skill tools name the available skills within the description cap', () => {
+  const unused = () => new Proxy({}, { get: () => undefined }) as never;
+
+  async function served(skills: readonly Skill[]) {
+    const registry = new ToolRegistry();
+    const skillService = { listSkills: async () => skills } as unknown as ISkillService;
+    registerSkillsTools(registry, express.Router(), ((_req, _res, next) => next()) as unknown as ToolAuth, createToolHandlerFactory(unused()), skillService);
+    const tools = await registry.listExternal();
+    return {
+      list: tools.find((t) => t.name === 'list_skills')!,
+      get: tools.find((t) => t.name === 'get_skill')!,
+    };
+  }
+
+  const skill = (name: string): Skill => ({ name, description: '', path: `Skills/${name}` }) as unknown as Skill;
+
+  it('names every skill when they fit, and says so plainly when there are none', async () => {
+    const few = await served(['rfi', 'deck-review'].map(skill));
+    for (const tool of [few.list, few.get]) {
+      expect(tool.description).toContain('Currently available skills: `rfi`, `deck-review`.');
+      expect(tool.description).not.toContain(' more');
+    }
+    const none = await served([]);
+    expect(none.list.description).toContain('No skills are currently available.');
+  });
+
+  it('lists every skill when the complete line fits, even where a shorter list plus its count would not', async () => {
+    // The budget is what the tool's fixed text leaves under the cap once the
+    // guide-first sentence is counted — read off a served description rather
+    // than guessed, so the names below are sized to fill it EXACTLY.
+    const probe = await served([skill('x')]);
+    const fixed = probe.list.description!.slice(GUIDE_FIRST_SENTENCE.length + 1, probe.list.description!.indexOf('Currently available skills: '));
+    // And the `Call:` line a client is handed ahead of all of it, with the
+    // blank line after it: the example counts toward the cap too.
+    const call = callLine(`KNOWLEDGE_BASE.list_skills`, probe.list.inputs).length + 2;
+    const budget = TOOL_DESCRIPTION_CAP - call - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
+    const head = 'Currently available skills: '.length;
+    // Twenty-one names, the LAST one short — shorter than the ", and 1 more…"
+    // tail a cut before it would carry — and the first one sized so the
+    // complete line is the budget to the character. A cut-then-count loop
+    // stops short of the complete list here (a prefix plus its count tail is
+    // over budget well before the last name) though the complete line fits.
+    const count = 21;
+    const base = Math.floor((budget - head - 1 - (count - 1) * 2 - count * 2) / count); // chars inside the backticks
+    const names = Array.from({ length: count }, (_, i) => `n${i}`.padEnd(base, 'x'));
+    names[count - 1] = 'z';
+    const slack = budget - (head + names.reduce((n, name) => n + name.length + 2, 0) + (count - 1) * 2 + 1);
+    names[0] = names[0] + 'y'.repeat(slack);
+    const { list } = await served(names.map(skill));
+    const line = list.description!.slice(list.description!.indexOf('Currently available skills: '));
+    expect(line.length).toBe(budget);
+    expect(line.endsWith('.')).toBe(true);
+    expect(line).not.toContain(' more');
+    for (const name of names) expect(line).toContain(`\`${name}\``);
+  });
+
+  it('cuts the list to what fits under the cap with the guide-first sentence counted, and counts the rest', async () => {
+    const many = Array.from({ length: 300 }, (_, i) => skill(`a-skill-with-a-long-name-number-${i}`));
+    const { list, get } = await served(many);
+    for (const tool of [list, get]) {
+      // Measured as the registry serves it: the opener in front.
+      expect(clientVisibleLength(tool), tool.name).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+      expect(tool.description!.startsWith(GUIDE_FIRST_SENTENCE), tool.name).toBe(true);
+      // The tool's own text is whole; the names are what gave way.
+      expect(tool.description, tool.name).toContain('Currently available skills: `a-skill-with-a-long-name-number-0`');
+      const counted = /, and (\d+) more that list_skills names\.$/.exec(tool.description!);
+      expect(counted, tool.name).not.toBeNull();
+      const shown = (tool.description!.match(/`a-skill-with-a-long-name-number-\d+`/g) ?? []).length;
+      expect(shown + Number(counted![1]), tool.name).toBe(300);
+      // No name is cut in half: every one listed is a real one, closing
+      // backtick included — a dangling name (no closing backtick) is caught
+      // because the scan does not require one.
+      for (const name of tool.description!.match(/`a-skill-with-a-long-name-number-[^`,.]*`?/g) ?? []) {
+        expect(name, tool.name).toMatch(/^`a-skill-with-a-long-name-number-\d+`$/);
+      }
+    }
+  });
+});

package/src/modules/skills/skills.tools.ts

@@ -1,9 +1,14 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import { callLine } from '@bevel-software/platform-mcp-core';
+import type { IToolRegistry, JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
+import { GUIDE_FIRST_SENTENCE } from '../tool-registry/guide-first.js';
 import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
+import { bodyEnvelope, declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { ISkillService } from './skills.contract.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';
 
 /**
@@ -20,6 +25,39 @@ const BRANCH_SKILLS_INPUT = {
     'a branch that does not exist answers 404 naming it. Omit it for the approved skills.',
 };
 
+/** What `list_skills` takes. A const so the route's check and the def share one declaration. */
+const LIST_SKILLS_INPUTS = {
+  type: 'object' as const,
+  properties: { branch: BRANCH_SKILLS_INPUT },
+  additionalProperties: false,
+};
+
+/** What `get_skill` takes. A const for the same reason as {@link LIST_SKILLS_INPUTS}. */
+const GET_SKILL_INPUTS = {
+  type: 'object' as const,
+  properties: {
+    name: { type: 'string' as const, minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
+    file: {
+      type: 'string' as const,
+      description:
+        'Optional bundled file path relative to the skill folder (e.g. `scripts/build_xlsx.py`) — ' +
+        'fetch its content instead of the body.',
+    },
+    version: {
+      type: 'string' as const,
+      description:
+        'Optional: the declared version to load (e.g. `1.4.0` — the `version` that `list_skills` ' +
+        'reports: `metadata.version`, else `version`, else `lifecycle.version`). Omitted, the skill is loaded as it ' +
+        'is now, which is the latest. Given, the skill — or the `file` — is served as it was at the most ' +
+        'recent commit that declared that version; a version the skill never declared answers ' +
+        '`version_not_found` with the versions it did declare.',
+    },
+    branch: BRANCH_SKILLS_INPUT,
+  },
+  required: ['name'],
+  additionalProperties: false,
+};
+
 /**
  * Registers the two skill tools (both surfaces) and hosts their endpoints.
  *
@@ -49,6 +87,11 @@ export function registerSkillsTools(
   registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
   registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
   registry.registerInternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+  // Both defs are built per catalog listing (their descriptions name the skills
+  // THIS caller may read), so declare the arguments here as well: a direct REST
+  // call that lands before the first listing must be checked against them too.
+  declareRouteTool('list_skills', LIST_SKILLS_INPUTS);
+  declareRouteTool('get_skill', GET_SKILL_INPUTS);
 
   router.post(
     '/agent/tools/list_skills',
@@ -97,31 +140,74 @@ function branchArg(args: Record<string, unknown>): string | undefined {
   return typeof branch === 'string' && branch.trim().length > 0 ? branch : undefined;
 }
 
-/** "Currently available skills: `a`, `b`." (or a no-skills note), filtered to what the caller may read. */
-async function availableSkillsLine(skillService: ISkillService, userEmail?: string): Promise<string> {
+/**
+ * "Currently available skills: `a`, `b`." (or a no-skills note), filtered to
+ * what the caller may read, and cut to `budget` characters: as many names as
+ * fit, then a count of the rest. The names are a convenience — `list_skills`
+ * is the complete answer — and a description a client cuts from the end
+ * would lose the tool's own tail to a catalog that grew; the budget is what
+ * the tool's fixed text leaves under {@link TOOL_DESCRIPTION_CAP} once the
+ * guide-first sentence the registry puts in front is counted.
+ */
+async function availableSkillsLine(skillService: ISkillService, userEmail: string | undefined, budget: number): Promise<string> {
   const skills = await skillService.listSkills(userEmail);
   if (skills.length === 0) return 'No skills are currently available.';
-  return `Currently available skills: ${skills.map((s) => `\`${s.name}\``).join(', ')}.`;
+  const names = skills.map((s) => `\`${s.name}\``);
+  const rest = (shown: number): string =>
+    shown < names.length ? `, and ${names.length - shown} more that list_skills names.` : '.';
+  const head = 'Currently available skills: ';
+  // The complete line first: it ends in a full stop, not in a count, so it
+  // can fit where a shorter list plus its "and N more" tail would not.
+  const complete = `${head}${names.join(', ')}.`;
+  if (complete.length <= budget) return complete;
+  // Otherwise one pass, accumulating: the cut is where the next name — with
+  // the separator before it and the tail that would follow it — no longer
+  // fits. (Rebuilding the joined prefix per candidate made this quadratic in
+  // the catalog's size, on every catalog listing.)
+  let shown = 0;
+  let length = head.length;
+  for (const name of names) {
+    const added = (shown > 0 ? 2 : 0) + name.length;
+    if (length + added + rest(shown + 1).length > budget) break;
+    length += added;
+    shown += 1;
+  }
+  if (shown === 0) {
+    return names.length === 1
+      ? '1 skill is currently available; list_skills names it.'
+      : `${names.length} skills are currently available; list_skills names them.`;
+  }
+  return `${head}${names.slice(0, shown).join(', ')}${rest(shown)}`;
 }
 
+/**
+ * What the fixed part of a description leaves the skills line, with the
+ * `Call:` line ahead of everything (and the blank line after it) and the
+ * guide-first sentence counted. The call line is generated from the schema
+ * the tool advertises: its flat `inputs` inside the `body` envelope.
+ */
+function skillsLineBudget(name: string, inputs: JsonSchema, fixed: string): number {
+  const call = callLine(`${EXTERNAL_KB_MANUAL_NAME}.${name}`, bodyEnvelope(inputs)).length + 2;
+  return TOOL_DESCRIPTION_CAP - call - GUIDE_FIRST_SENTENCE.length - 1 - fixed.length;
+}
+
+const LIST_SKILLS_DESCRIPTION =
+  'List the available skills (reusable specialist instructions) with their names, descriptions and, ' +
+  'for a skill that declares one, its current `version` (its SKILL.md `metadata.version`, else a ' +
+  'top-level `version`, else `lifecycle.version`). ' +
+  'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
+  'Pass `branch` to list the skills as they are on a draft branch instead of the released set — ' +
+  'what you need to try a skill you just wrote there; each skill that differs from the released ' +
+  'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ';
+
 async function buildListSkillsDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
     name: 'list_skills',
     description:
-      'List the available skills (reusable specialist instructions) with their names, descriptions and, ' +
-      'for a skill that declares one, its current `version` (its SKILL.md `metadata.version`, else a ' +
-      'top-level `version`, else `lifecycle.version`). ' +
-      'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
-      'Pass `branch` to list the skills as they are on a draft branch instead of the released set — ' +
-      'what you need to try a skill you just wrote there; each skill that differs from the released ' +
-      'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ' +
-      (await availableSkillsLine(skillService, userEmail)),
+      LIST_SKILLS_DESCRIPTION +
+      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('list_skills', LIST_SKILLS_INPUTS, LIST_SKILLS_DESCRIPTION))),
     path: '/api/agent/tools/list_skills',
-    inputs: {
-      type: 'object',
-      properties: { branch: BRANCH_SKILLS_INPUT },
-      additionalProperties: false,
-    },
+    inputs: LIST_SKILLS_INPUTS,
     outputs: {
       type: 'object',
       properties: {
@@ -156,40 +242,20 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
   });
 }
 
+const GET_SKILL_DESCRIPTION =
+  'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
+  'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
+  '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
+  'one the skill declared, or `branch` names a draft to load it from. ';
+
 async function buildGetSkillDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
     name: 'get_skill',
     description:
-      'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
-      'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
-      '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
-      'one the skill declared, or `branch` names a draft to load it from. ' +
-      (await availableSkillsLine(skillService, userEmail)),
+      GET_SKILL_DESCRIPTION +
+      (await availableSkillsLine(skillService, userEmail, skillsLineBudget('get_skill', GET_SKILL_INPUTS, GET_SKILL_DESCRIPTION))),
     path: '/api/agent/tools/get_skill',
-    inputs: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
-        file: {
-          type: 'string',
-          description:
-            'Optional bundled file path relative to the skill folder (e.g. `scripts/build_xlsx.py`) — ' +
-            'fetch its content instead of the body.',
-        },
-        version: {
-          type: 'string',
-          description:
-            'Optional: the declared version to load (e.g. `1.4.0` — the `version` that `list_skills` ' +
-            'reports: `metadata.version`, else `version`, else `lifecycle.version`). Omitted, the skill is loaded as it ' +
-            'is now, which is the latest. Given, the skill — or the `file` — is served as it was at the most ' +
-            'recent commit that declared that version; a version the skill never declared answers ' +
-            '`version_not_found` with the versions it did declare.',
-        },
-        branch: BRANCH_SKILLS_INPUT,
-      },
-      required: ['name'],
-      additionalProperties: false,
-    },
+    inputs: GET_SKILL_INPUTS,
     outputs: {
       type: 'object',
       description: 'On success carries `skill` (or `file` when `file` was passed); on failure carries `error`.',

package/src/modules/tool-auth/__tests__/connection-key-rejection.test.ts

@@ -11,6 +11,7 @@ import type { AuthService } from '../../auth/auth.service.js';
 import { InternalTokenService } from '../internal-token.service.js';
 import { createManualAuthMiddleware, createToolAuthMiddleware } from '../tool-auth.middleware.js';
 import type { IExternalApiKeyService } from '../external-api-key.interface.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE } from '../../auth/account-admission.js';
 
 /**
  * A bearer shaped like a connection key that does not verify is answered with
@@ -24,6 +25,8 @@ import type { IExternalApiKeyService } from '../external-api-key.interface.js';
  * server requests, with the same gate `create-core-server.ts` puts on each.
  */
 const BAD_KEY = 'bevel_revokedKeyThatMustNeverBeEchoed';
+/** A second refused key: on the switched-off service it is not one of a switched-off account. */
+const OTHER_BAD_KEY = 'bevel_unknownKeyThatMustNeverBeEchoed';
 const RESOURCE_METADATA_URL = 'https://hexis.example/.well-known/oauth-protected-resource/api/mcp';
 const DISCOVERY_CHALLENGE = `Bearer realm="bevel-mcp", resource_metadata="${RESOURCE_METADATA_URL}"`;
 const KEY_CHALLENGE = 'Bearer error="invalid_token", error_description="Invalid or revoked connection key"';
@@ -190,3 +193,32 @@ describe('the REST agent surface keeps its challenge for everything but a key',
     }
   });
 });
+
+describe('a live connection key whose account is switched off is told so', () => {
+  const switchedOffKeys = {
+    ...externalApiKeys,
+    isKeyOfSwitchedOffAccount: async (t: string) => t === BAD_KEY,
+  } as unknown as IExternalApiKeyService;
+
+  for (const endpoint of KEY_ENDPOINTS) {
+    it(`${endpoint.name}: 401 with the switched-off reason, not an invitation to mint a new key`, async () => {
+      const base = await start(switchedOffKeys);
+      const res = await call(base, endpoint.method, endpoint.path, BAD_KEY);
+      expect(res.status).toBe(401);
+      expect(res.headers.get('www-authenticate')).toBe(
+        'Bearer error="invalid_token", error_description="The account of this connection key is switched off"',
+      );
+      expect(await res.json()).toEqual({ error: ACCOUNT_DEACTIVATED_MESSAGE });
+      expect(logged.join('\n')).not.toContain(BAD_KEY);
+    });
+
+    it(`${endpoint.name}: any other refused key on the same service is still told it is invalid`, async () => {
+      const base = await start(switchedOffKeys);
+      const res = await call(base, endpoint.method, endpoint.path, OTHER_BAD_KEY);
+      expect(res.status).toBe(401);
+      expect(res.headers.get('www-authenticate')).toBe(KEY_CHALLENGE);
+      expect(await res.json()).toEqual(KEY_BODY);
+      expect(logged.join('\n')).not.toContain(OTHER_BAD_KEY);
+    });
+  }
+});

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

@@ -276,6 +276,71 @@ describe('ExternalApiKeyService', () => {
       expect(warn).toHaveBeenCalled();
       warn.mockRestore();
     });
+
+    /**
+     * A key's FIRST use is an agent arriving — what the onboarding waits for
+     * — so the owner is told once the stamp has landed, and once only. The
+     * first stamp is a CLAIM (`… where last_used_at is null … returning`):
+     * the request the database hands the row to announces, a racing one
+     * loses the claim, stamps the ordinary way and says nothing, and a key
+     * stamped before is touched without a word.
+     */
+    it("announces a key's first use to its owner once the claim has landed, and never otherwise", async () => {
+      const row = { tokenId: 'tok-1', label: 'Laptop', lastUsedAt: null, userId: 'user-7', email: 'a@x.io', name: 'Alice', avatarUrl: null };
+      const events = { emit: vi.fn() };
+      // The claim's answer is held back, to pin that the announcement waits for it.
+      let claimed!: (rows: { id: string }[]) => void;
+      const claim = new Promise<{ id: string }[]>((resolve) => (claimed = resolve));
+      const first = makeFakeDb([[row], claim]);
+      await new ExternalApiKeyService(first.db, 'bevel_', {}, events).verifyAndLoadUser('bevel_abc');
+      await flushMicrotasks();
+      expect(first.calls.update).toHaveLength(1);
+      expect(first.calls.set[0][0]).toHaveProperty('lastUsedAt');
+      expect(renderSql(first.calls.where[1][0]).sql).toMatch(/"api_tokens"."id" = \$1 and "api_tokens"."last_used_at" is null/);
+      expect(events.emit).not.toHaveBeenCalled();
+      claimed([{ id: 'tok-1' }]);
+      await flushMicrotasks();
+      expect(events.emit).toHaveBeenCalledTimes(1);
+      expect(events.emit).toHaveBeenCalledWith({
+        kind: 'agent-connected',
+        forUserId: 'user-7',
+        client: 'Laptop',
+        agentKind: 'key',
+        at: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+      });
+
+      // A racing request lost the claim: the ordinary stamp, and no announcement.
+      const lost = makeFakeDb([[row], [], undefined]);
+      const lostEvents = { emit: vi.fn() };
+      await new ExternalApiKeyService(lost.db, 'bevel_', {}, lostEvents).verifyAndLoadUser('bevel_abc');
+      await flushMicrotasks();
+      expect(lost.calls.update).toHaveLength(2);
+      expect(lostEvents.emit).not.toHaveBeenCalled();
+
+      // A key stamped before: touched, and nobody is told.
+      const again = makeFakeDb([[{ ...row, lastUsedAt: new Date('2026-10-07T12:00:00Z') }], undefined]);
+      const laterEvents = { emit: vi.fn() };
+      await new ExternalApiKeyService(again.db, 'bevel_', {}, laterEvents).verifyAndLoadUser('bevel_abc');
+      await flushMicrotasks();
+      expect(again.calls.update).toHaveLength(1);
+      expect(laterEvents.emit).not.toHaveBeenCalled();
+    });
+
+    it('announces nothing when the first stamp could not be written', async () => {
+      const row = { tokenId: 'tok-1', label: 'Laptop', lastUsedAt: null, userId: 'user-7', email: 'a@x.io', name: 'Alice', avatarUrl: null };
+      let fail!: (err: Error) => void;
+      const claim = new Promise<{ id: string }[]>((_resolve, reject) => (fail = reject));
+      const { db } = makeFakeDb([[row], claim]);
+      const events = { emit: vi.fn() };
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const user = await new ExternalApiKeyService(db, 'bevel_', {}, events).verifyAndLoadUser('bevel_abc');
+      expect(user?.id).toBe('user-7');
+      fail(new Error('connection lost'));
+      await flushMicrotasks();
+      expect(events.emit).not.toHaveBeenCalled();
+      expect(warn).toHaveBeenCalled();
+      warn.mockRestore();
+    });
   });
 
   describe('listForUser', () => {

package/src/modules/tool-auth/connection-key-rejection.ts

@@ -1,4 +1,5 @@
 import type { Response } from 'express';
+import { ACCOUNT_DEACTIVATED_MESSAGE } from '../auth/account-admission.js';
 
 /**
  * How every key-authenticated endpoint answers a bearer that LOOKS like a
@@ -19,7 +20,16 @@ export const INVALID_CONNECTION_KEY_CHALLENGE =
 export const INVALID_CONNECTION_KEY_MESSAGE =
   'Invalid or revoked connection key. Mint a new one in External agent access.';
 
-export function rejectConnectionKey(res: Response): void {
-  res.setHeader('WWW-Authenticate', INVALID_CONNECTION_KEY_CHALLENGE);
-  res.status(401).json({ error: INVALID_CONNECTION_KEY_MESSAGE });
+/**
+ * A live key whose account an admin switched off: still a plain
+ * `invalid_token` (no sign-in invitation, see above), but told the real
+ * reason — telling them to mint a new key would send them to something
+ * they cannot do.
+ */
+export const SWITCHED_OFF_CONNECTION_KEY_CHALLENGE =
+  'Bearer error="invalid_token", error_description="The account of this connection key is switched off"';
+
+export function rejectConnectionKey(res: Response, opts: { switchedOff?: boolean } = {}): void {
+  res.setHeader('WWW-Authenticate', opts.switchedOff ? SWITCHED_OFF_CONNECTION_KEY_CHALLENGE : INVALID_CONNECTION_KEY_CHALLENGE);
+  res.status(401).json({ error: opts.switchedOff ? ACCOUNT_DEACTIVATED_MESSAGE : INVALID_CONNECTION_KEY_MESSAGE });
 }

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

@@ -140,6 +140,15 @@ export interface IExternalApiKeyService {
     plaintext: string,
   ): Promise<{ tokenId: string; user: AuthUser } | null>;
 
+  /**
+   * For a key {@link verifyAndLoadToken} refused: whether it is a live key
+   * whose account an admin switched off — the one refusal its holder must
+   * not be told to mint a new key over (they cannot; the account is off).
+   * Asked only on the refusal path, so a working key costs nothing more.
+   * Optional: without it every refused key is reported as invalid.
+   */
+  isKeyOfSwitchedOffAccount?(plaintext: string): Promise<boolean>;
+
   /** Active + revoked tokens for the user, newest-first. */
   listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
 

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

@@ -3,7 +3,7 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('external-api-key');
 import { and, desc, eq, isNotNull, isNull, type SQL } from 'drizzle-orm';
-import type { AuthUser } from '@bevel-software/platform-shared';
+import type { AgentConnectedEvent, AuthUser } from '@bevel-software/platform-shared';
 import type { Database } from '../database/connection.js';
 import { externalApiKeys, users } from '../database/schema.js';
 import {
@@ -51,6 +51,12 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     private readonly db: Database,
     private readonly keyPrefix: string,
     private readonly kinds: Readonly<Record<string, KeyKindSpec>> = {},
+    /**
+     * Where a key's FIRST use is announced to its owner (`agent-connected`,
+     * see `verifyAndLoadToken`). Optional: without it the stamp is written
+     * and nobody is told.
+     */
+    private readonly events?: { emit(event: AgentConnectedEvent): void },
   ) {
     this.prefixes = [keyPrefix, ...Object.values(kinds).map((k) => k.prefix)];
   }
@@ -97,6 +103,19 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     return resolved ? resolved.user : null;
   }
 
+  async isKeyOfSwitchedOffAccount(plaintext: string): Promise<boolean> {
+    if (!this.looksLikeExternalApiKey(plaintext)) return false;
+    // The same key `verifyAndLoadToken` would accept (known, not revoked),
+    // but on an account that is off.
+    const [row] = await this.db
+      .select({ id: externalApiKeys.id })
+      .from(externalApiKeys)
+      .innerJoin(users, eq(externalApiKeys.userId, users.id))
+      .where(and(eq(externalApiKeys.tokenHash, hashToken(plaintext)), isNull(externalApiKeys.revokedAt), isNotNull(users.deactivatedAt)))
+      .limit(1);
+    return row !== undefined;
+  }
+
   async verifyAndLoadToken(
     plaintext: string,
   ): Promise<{ tokenId: string; user: AuthUser } | null> {
@@ -114,6 +133,8 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     const [row] = await this.db
       .select({
         tokenId: externalApiKeys.id,
+        label: externalApiKeys.label,
+        lastUsedAt: externalApiKeys.lastUsedAt,
         userId: users.id,
         email: users.email,
         name: users.name,
@@ -130,9 +151,28 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // the UPDATE. A failed touch is logged but never blocks the caller —
     // the worst case is a slightly stale `last_used_at`, which is fine for
     // a "when was this key last used" audit view.
-    this.touchLastUsed(row.tokenId).catch((err) => {
-      log.warn('touchLastUsed failed:', { err });
-    });
+    //
+    // A key's FIRST use is an agent that has just reached the platform —
+    // what the onboarding waits for — so its owner is told once the stamp
+    // has landed. A key never stamped is CLAIMED (`claimFirstUse`), so of
+    // two requests racing its first use exactly one announces it; a key
+    // stamped before is touched and nobody is told.
+    const stamped = row.lastUsedAt === null ? this.claimFirstUse(row.tokenId) : this.touchLastUsed(row.tokenId).then(() => false);
+    stamped.then(
+      (first) => {
+        if (!first) return;
+        this.events?.emit({
+          kind: 'agent-connected',
+          forUserId: row.userId,
+          client: row.label,
+          agentKind: 'key',
+          at: new Date().toISOString(),
+        });
+      },
+      (err) => {
+        log.warn('touchLastUsed failed:', { err });
+      },
+    );
 
     return {
       tokenId: row.tokenId,
@@ -280,6 +320,23 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       .set({ lastUsedAt: new Date() })
       .where(eq(externalApiKeys.id, tokenId));
   }
+
+  /**
+   * The first stamp as ONE statement: the row is taken only while
+   * `last_used_at` is still null, so of two requests (or two replicas)
+   * racing a key's first use the database hands it to exactly one, which
+   * answers true. The loser stamps the ordinary way and answers false.
+   */
+  private async claimFirstUse(tokenId: string): Promise<boolean> {
+    const won = await this.db
+      .update(externalApiKeys)
+      .set({ lastUsedAt: new Date() })
+      .where(and(eq(externalApiKeys.id, tokenId), isNull(externalApiKeys.lastUsedAt)))
+      .returning({ id: externalApiKeys.id });
+    if (won.length > 0) return true;
+    await this.touchLastUsed(tokenId);
+    return false;
+  }
 }
 
 function hashToken(plaintext: string): string {

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

@@ -6,7 +6,11 @@ import type { IExternalApiKeyService } from './external-api-key.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
 import { ACCOUNT_DEACTIVATED_MESSAGE, AuthBackendError } from '../auth/account-admission.js';
 import { InternalTokenService } from './internal-token.service.js';
-import { INVALID_CONNECTION_KEY_CHALLENGE, INVALID_CONNECTION_KEY_MESSAGE } from './connection-key-rejection.js';
+import {
+  INVALID_CONNECTION_KEY_CHALLENGE,
+  INVALID_CONNECTION_KEY_MESSAGE,
+  SWITCHED_OFF_CONNECTION_KEY_CHALLENGE,
+} from './connection-key-rejection.js';
 
 /**
  * What the `toolAuth` middleware resolves a bearer to, before the per-call
@@ -165,9 +169,14 @@ export function createTokenVerifier(
     // External API key → external caller. (verifyAndLoadToken may throw → propagates → caller maps to 500.)
     if (externalApiKeyService.looksLikeExternalApiKey(token)) {
       const resolved = await externalApiKeyService.verifyAndLoadToken(token);
-      return resolved
-        ? { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } }
-        : { ok: false, status: 401, message: INVALID_CONNECTION_KEY_MESSAGE, challenge: INVALID_CONNECTION_KEY_CHALLENGE };
+      if (resolved) {
+        return { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } };
+      }
+      // A live key of a switched-off account is told so, not sent to mint another.
+      if (await externalApiKeyService.isKeyOfSwitchedOffAccount?.(token)) {
+        return { ok: false, status: 401, message: ACCOUNT_DEACTIVATED_MESSAGE, challenge: SWITCHED_OFF_CONNECTION_KEY_CHALLENGE };
+      }
+      return { ok: false, status: 401, message: INVALID_CONNECTION_KEY_MESSAGE, challenge: INVALID_CONNECTION_KEY_CHALLENGE };
     }
 
     return missing;