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

package/src/modules/agent-instructions/__tests__/shared-file-rules.test.ts

@@ -114,6 +114,20 @@ describe('the shared file rules are one text, in two places', () => {
 
 });
 
+describe('the delete rule for platform files', () => {
+  const managedItems = (): string => sharedFileRules(DEFAULT_KB_LAYOUT).find((r) => r.id === 'managed-items')!.body;
+
+  it('says a nested access.md is deleted by whoever may write it, and the root\'s platform files by nobody', async () => {
+    const body = managedItems();
+    expect(body).toContain('delete_file deletes a nested `access.md` for whoever may write it');
+    expect(body).toContain("its folder then follows its parent's rules");
+    expect(body).toContain("the repository root's `access.md` and `roles.yaml` are deleted by nobody");
+    // The sentence the refusal actually carries, as the tools and the app say it.
+    expect(body).toContain("\"<name> is the repository's own file and cannot be deleted.\"");
+    expect(await composeAgentGuide(DEFAULT_KB_LAYOUT)).toContain(body);
+  });
+});
+
 describe('the handshake text stays inside the length it pins', () => {
   it('holds the shared section under its own cap', () => {
     const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT);

package/src/modules/agent-instructions/compose.ts

@@ -30,6 +30,7 @@ import {
   stripHtmlComments,
   type KbLayout,
 } from '@bevel-software/platform-shared';
+import { splitCallLine } from '@bevel-software/platform-mcp-core';
 import { sharedFileRulesSection } from './shared-file-rules.js';
 
 export { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP };
@@ -48,7 +49,13 @@ export const PLATFORM_HEADER =
   'Before answering a question about the organisation, its people, customers, products, processes, projects or internal terms, ' +
   'search the knowledge base: call `start_session` once, then `grep` for the key terms, `list_files` to orient, and `read_file` what matches. ' +
   'Prefer what you find there over memory or the web, and say so when the knowledge base is silent on something the organisation should have documented. ' +
-  'Skills are available as prompts and through `list_skills` and `get_skill`.';
+  'Skills are available as prompts and through `list_skills` and `get_skill`. ' +
+  // There is no one calling shape to state: the knowledge-base tools take
+  // their arguments under `body`, a tool that calls another service takes them
+  // flat, and an agent told one rule for all of them sends a GET with a body.
+  // The per-tool `Call:` line is generated from each tool's own input schema,
+  // so pointing at it is both shorter and always right.
+  'Tools do not share one calling shape: call each tool exactly as the `Call:` line at the top of its description shows.';
 
 /**
  * The fixed first line of the tool prefix. It always leads, so an admin's
@@ -167,9 +174,17 @@ export function composeAgentInstructions(
  * A tool description with the prefix ahead of it: the prefix, a blank line,
  * then the original. Purpose line first, because claude.ai cuts descriptions
  * near 500 characters.
+ *
+ * Except for the `Call:` line, which stays the very first line whatever else
+ * is prepended: it is how an agent learns the shape this tool's arguments take,
+ * and a description that opens with the purpose prefix instead would bury the
+ * one line the refusal for a wrong call points back to.
  */
 export function prefixToolDescription(toolPrefix: string, description: string | undefined): string {
-  return description ? `${toolPrefix}\n\n${description}` : toolPrefix;
+  if (!description) return toolPrefix;
+  const { call, rest } = splitCallLine(description);
+  if (call === null) return `${toolPrefix}\n\n${description}`;
+  return rest === '' ? `${call}\n\n${toolPrefix}` : `${call}\n\n${toolPrefix}\n\n${rest}`;
 }
 
 /** An ATX heading line: `#` to `######`, then a space or the end. */

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -145,15 +145,15 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
       // that take content as a JSON string names the route in one sentence of
       // its own; WHY a file should go that way, and how, is here.
       id: 'upload-route',
-      heading: 'Large, escape-heavy and binary content goes by upload',
+      heading: 'Large, escape-heavy and binary content: upload in, download out',
       body:
-        'write_file, write_files and edit_file take content as a JSON string you have to type out in full, so a long ' +
-        'file is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and ' +
-        'an image, a PDF or a zip cannot be sent at all. For any of those: call `request_file_upload`, POST the file — ' +
-        'or one zip holding many files — to the address it answers with any HTTP client ' +
-        '(`curl -X POST --data-binary @<file> "<uploadUrl>?filename=<name>"`), then `apply_file_upload` to land it on ' +
-        'a branch in one commit. The bytes never pass through the conversation, so nothing is cut or mangled on the ' +
-        'way. A person can also use Upload in the app.',
+        'write_file, write_files and edit_file take content as a JSON string you type out in full, so a long file ' +
+        'is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and an ' +
+        'image, a PDF or a zip cannot be sent at all. For those, call `request_file_upload`, POST the file (or one ' +
+        'zip of many) with any HTTP client (`curl -X POST --data-binary @<file> ' +
+        '"<uploadUrl>?filename=<name>"`), then `apply_file_upload` lands it in one commit. To take copies OUT, ' +
+        '`request_file_download` answers a one-time link per file and a zip per folder (`curl -o <name> ' +
+        '"<downloadUrl>"`). Either way no bytes pass through the conversation.',
     },
     {
       id: 'dry-run-confirm',
@@ -163,22 +163,22 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
         'what the call would touch, `allowed`, and `reason` when it may not run. A non-empty folder is deleted, and a ' +
         'move that changes your access runs, only with `confirm: true`; without it the call changes nothing and ' +
         'returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — ' +
-        'dry-run, check the impact, then confirm. delete_file takes neither: it removes the one file you named, so ' +
-        'check it first with file_stat (`deletable`) if you are unsure.',
+        'dry-run, check the impact, then confirm. delete_file takes neither: check it first with file_stat ' +
+        '(`deletable`) if you are unsure. delete_branch has its own `dryRun`.',
     },
     {
       id: 'managed-items',
       heading: 'What these tools never move or delete',
       body:
-        `A platform file (${platformFileList(layout)}) is refused with ` +
-        '"<name> is a platform file and stays in its folder." — a folder that moves ' +
-        'takes its own platform files along, still in their folder, and a folder that is deleted takes them with it in ' +
-        'the same one change, so its files are never left ungoverned part-way. A platform folder (the repository root ' +
-        `or a reserved root folder such as \`${layout.knowledgeBaseDir}/\`) and git metadata are refused, and so is creating a ` +
-        'platform file or folder at a destination (renaming a note to `access.md` is refused). A path that is, or goes ' +
-        'through, a symbolic link is refused: links are never followed or removed. On a protected branch you must be ' +
-        'able to write everything the call touches — for a folder, every file under it, at its old and its new path. ' +
-        'file_stat reports `managed`, `movable` and `deletable` so you can tell before the call.',
+        `A platform file (${platformFileList(layout)}) is never moved: "<name> is a platform file and stays in its folder." ` +
+        'A folder moved or deleted takes its own along, in one change. delete_file deletes a nested `access.md` for ' +
+        "whoever may write it (its folder then follows its parent's rules) and refuses `.bevelignore`; the repository " +
+        "root's `access.md` and `roles.yaml` are deleted by nobody: \"<name> is the repository's own file and cannot be " +
+        'deleted." A platform folder (the root, or a reserved one like ' +
+        `\`${layout.knowledgeBaseDir}/\`), git metadata, and making a platform file or folder at a destination are ` +
+        'refused; so is a path that is or crosses a symlink: links are never followed or removed. On a protected ' +
+        'branch you must be able to write all a call touches — for a folder, every file under it, at its old and new ' +
+        'path. file_stat reports `managed`, `movable` and `deletable` up front.',
     },
     {
       id: 'refused-for-permissions',

package/src/modules/audit/__tests__/agent-audit.service.test.ts

@@ -14,13 +14,17 @@ import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.in
  * update / delete` pops the next queued result. `transaction` runs its
  * callback against the same fake, so queued results are consumed in order.
  * Every `where` predicate and `update` target is captured, so a test can pin
- * WHICH rows a statement addressed (see {@link render}), not just that it ran.
+ * WHICH rows a statement addressed (see {@link render}), not just that it ran;
+ * `orderBy` and `limit` too, since the fake applies neither and a test can
+ * only pin WHICH row of several a read keeps by the clauses it sent.
  */
 function makeFakeDb(queue: unknown[]) {
-  const captured: { values: any[]; set: any[]; where: SQL[]; updateTargets: unknown[] } = {
+  const captured: { values: any[]; set: any[]; where: SQL[]; orderBy: SQL[][]; limit: number[]; updateTargets: unknown[] } = {
     values: [],
     set: [],
     where: [],
+    orderBy: [],
+    limit: [],
     updateTargets: [],
   };
   const counts = { insert: 0, select: 0, update: 0, delete: 0 };
@@ -36,10 +40,10 @@ function makeFakeDb(queue: unknown[]) {
     chain.values = passthrough((a) => captured.values.push(a[0]));
     chain.set = passthrough((a) => captured.set.push(a[0]));
     chain.where = passthrough((a) => captured.where.push(a[0]));
-    chain.limit = passthrough();
+    chain.limit = passthrough((a) => captured.limit.push(a[0]));
     chain.innerJoin = passthrough();
     chain.from = passthrough();
-    chain.orderBy = passthrough();
+    chain.orderBy = passthrough((a) => captured.orderBy.push(a));
     chain.groupBy = passthrough();
     chain.returning = passthrough();
     chain.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR);
@@ -355,6 +359,62 @@ describe('AgentAuditService.revokeConnection', () => {
   });
 });
 
+/**
+ * The onboarding's "is your agent connected yet?". The page polls it, so the
+ * contract worth pinning is what it reads (one person's LIVE, USED rows of
+ * each kind — never the event log) and how the two kinds are combined.
+ */
+describe('AgentAuditService.lastAgentUse', () => {
+  it('answers null when neither an agent connection nor a key has been used', async () => {
+    const { service, counts } = makeService([[] /* connections */, [] /* keys */]);
+    await expect(service.lastAgentUse(ALICE.id)).resolves.toBeNull();
+    expect(counts.select).toBe(2);
+  });
+
+  it("reads only the caller's live, used rows of each kind", async () => {
+    const { service, captured } = makeService([[], []]);
+    await service.lastAgentUse(ALICE.id);
+    const [connections, keys] = captured.where.map(render);
+    expect(connections!.sql).toContain('"agent_connections"."user_id" = $1');
+    expect(connections!.sql).toContain('"agent_connections"."revoked_at" is null');
+    expect(connections!.sql).toContain('"agent_connections"."last_used_at" is not null');
+    expect(connections!.params).toEqual([ALICE.id]);
+    expect(keys!.sql).toContain('"api_tokens"."user_id" = $1');
+    expect(keys!.sql).toContain('"api_tokens"."revoked_at" is null');
+    expect(keys!.sql).toContain('"api_tokens"."last_used_at" is not null');
+    expect(keys!.params).toEqual([ALICE.id]);
+  });
+
+  it('keeps the most recently used row of each kind, of however many a person has', async () => {
+    // The fake neither sorts nor limits, so what is pinned is what each read
+    // asks the database for: newest use first, one row.
+    const { service, captured } = makeService([[], []]);
+    await service.lastAgentUse(ALICE.id);
+    expect(captured.orderBy.map((clauses) => clauses.map((c) => render(c).sql))).toEqual([
+      ['"agent_connections"."last_used_at" desc'],
+      ['"api_tokens"."last_used_at" desc'],
+    ]);
+    expect(captured.limit).toEqual([1, 1]);
+  });
+
+  it("names an agent connection by its client, and an unnamed one as such", async () => {
+    const at = new Date(NOW - 60_000);
+    const named = makeService([[{ client: 'Claude', at }], []]);
+    await expect(named.service.lastAgentUse(ALICE.id)).resolves.toEqual({ at, client: 'Claude', kind: 'agent' });
+    const unnamed = makeService([[{ client: null, at }], []]);
+    await expect(unnamed.service.lastAgentUse(ALICE.id)).resolves.toEqual({ at, client: 'Unnamed agent', kind: 'agent' });
+  });
+
+  it('answers with the newer of the two when both kinds have been used', async () => {
+    const older = new Date(NOW - DAY);
+    const newer = new Date(NOW - 60_000);
+    const keyNewer = makeService([[{ client: 'Claude', at: older }], [{ client: 'Laptop', at: newer }]]);
+    await expect(keyNewer.service.lastAgentUse(ALICE.id)).resolves.toEqual({ at: newer, client: 'Laptop', kind: 'key' });
+    const agentNewer = makeService([[{ client: 'Claude', at: newer }], [{ client: 'Laptop', at: older }]]);
+    await expect(agentNewer.service.lastAgentUse(ALICE.id)).resolves.toEqual({ at: newer, client: 'Claude', kind: 'agent' });
+  });
+});
+
 describe('retentionDaysFrom', () => {
   it('reads a positive whole number of days, and blank, zero or negative as forever', () => {
     expect(retentionDaysFrom('30')).toBe(30);

package/src/modules/audit/__tests__/agent-connection.routes.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAgentConnectionRoutes } from '../agent-connection.routes.js';
+import type { AgentUse, IAgentConnectionStatus } from '../audit.contract.js';
+
+/**
+ * GET /onboarding/agent-connection — what the connect-your-agent page polls.
+ * The contract worth pinning:
+ *
+ *  - it answers for the AUTHENTICATED user (req.userId) and nobody else;
+ *    nothing in the request — query or otherwise — can name another account;
+ *  - "not yet" and "connected" are the two shapes, the second with when, as
+ *    what, and whether that name is an agent's or a connection key's label;
+ *  - the answer is never cached, since the next poll expects it to change;
+ *  - a failure is a generic 500, never the driver's message.
+ */
+
+const ALICE = 'u-alice';
+const BOB = 'u-bob';
+const CARA = 'u-cara';
+
+const USES: Record<string, AgentUse> = {
+  [BOB]: { at: new Date(Date.UTC(2026, 9, 7, 12, 0, 0)), client: 'Claude', kind: 'agent' },
+  [CARA]: { at: new Date(Date.UTC(2026, 9, 7, 13, 0, 0)), client: 'Laptop', kind: 'key' },
+};
+
+const status = {
+  lastAgentUse: vi.fn(async (userId: string) => USES[userId] ?? null),
+} satisfies IAgentConnectionStatus;
+
+let server: Server | undefined;
+afterEach(() => {
+  server?.close();
+  server = undefined;
+  vi.clearAllMocks();
+  vi.restoreAllMocks();
+});
+
+/** Mount the route with a stand-in auth middleware stamping `as` as the caller. */
+async function listen(as: string): Promise<string> {
+  const app = express();
+  app.use((req, _res, next) => {
+    req.userId = as;
+    next();
+  });
+  app.use('/api', createAgentConnectionRoutes(status));
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server!.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+describe('GET /onboarding/agent-connection', () => {
+  it('says "not yet" for a caller whose agents have not been used', async () => {
+    const base = await listen(ALICE);
+    const res = await fetch(`${base}/api/onboarding/agent-connection`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ connected: false });
+    expect(status.lastAgentUse).toHaveBeenCalledWith(ALICE);
+  });
+
+  it('says connected, with when and as what, once one has', async () => {
+    const base = await listen(BOB);
+    const res = await fetch(`${base}/api/onboarding/agent-connection`);
+    expect(await res.json()).toEqual({ connected: true, at: '2026-10-07T12:00:00.000Z', client: 'Claude', kind: 'agent' });
+  });
+
+  it("keeps a connection key's kind: its label says nothing about which app holds it", async () => {
+    const base = await listen(CARA);
+    const res = await fetch(`${base}/api/onboarding/agent-connection`);
+    expect(await res.json()).toEqual({ connected: true, at: '2026-10-07T13:00:00.000Z', client: 'Laptop', kind: 'key' });
+  });
+
+  it("answers for the caller alone — a named account in the query is not asked about", async () => {
+    const base = await listen(ALICE);
+    const res = await fetch(`${base}/api/onboarding/agent-connection?userId=${BOB}&user=${BOB}`);
+    expect(await res.json()).toEqual({ connected: false });
+    expect(status.lastAgentUse).toHaveBeenCalledTimes(1);
+    expect(status.lastAgentUse).toHaveBeenCalledWith(ALICE);
+  });
+
+  it('is never cached: the next poll expects a different answer', async () => {
+    const base = await listen(ALICE);
+    const res = await fetch(`${base}/api/onboarding/agent-connection`);
+    expect(res.headers.get('cache-control')).toBe('no-store');
+  });
+
+  it('reports a failed read as a generic 500, keeping the detail server-side', async () => {
+    const detail = 'connection to 10.0.0.4:5432 refused';
+    status.lastAgentUse.mockRejectedValueOnce(new Error(detail));
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const base = await listen(ALICE);
+    const res = await fetch(`${base}/api/onboarding/agent-connection`);
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe('Could not check your agent');
+    expect(body.error).not.toContain(detail);
+  });
+});

package/src/modules/audit/agent-audit.service.ts

@@ -1,7 +1,7 @@
-import { and, count, desc, eq, isNull, lt, or, type SQL } from 'drizzle-orm';
+import { and, count, desc, eq, isNotNull, isNull, lt, or, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 import type { Database } from '../database/connection.js';
-import { agentConnections, agentEvents, oauthTokens, users } from '../database/schema.js';
+import { agentConnections, agentEvents, externalApiKeys, oauthTokens, users } from '../database/schema.js';
 import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
 import {
   AuditPrincipalNotFoundError,
@@ -11,10 +11,12 @@ import {
   type AgentEventInput,
   type AgentEventPage,
   type AgentEventView,
+  type AgentUse,
   type AuditPrincipal,
   type AuditPrincipalRef,
   type AuditScope,
   type IAgentAuditService,
+  type IAgentConnectionStatus,
   type IAgentEventRecorder,
 } from './audit.contract.js';
 
@@ -39,7 +41,7 @@ const PRUNE_INTERVAL_MS = 60 * 60_000;
  * Connection keys are read through the key service rather than joined here,
  * so their summary shape (kind, revoked-by, …) has exactly one definition.
  */
-export class AgentAuditService implements IAgentAuditService, IAgentEventRecorder {
+export class AgentAuditService implements IAgentAuditService, IAgentEventRecorder, IAgentConnectionStatus {
   private lastPruneAt = 0;
 
   constructor(
@@ -242,6 +244,59 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
     };
   }
 
+  /**
+   * Whether one person's agent has reached the platform yet — what the
+   * onboarding asks once on arrival (the `agent-connected` event the stamp
+   * paths emit tells it the moment it changes). Two single-row reads on the
+   * per-user indexes, never a scan of the event log.
+   *
+   * Read from the `last_used_at` stamps, not from `agent_events`: an agent
+   * stamps its connection (or key) on its FIRST authenticated request — the
+   * `initialize` / `tools/list` every client sends straight after connecting
+   * — while an event is written only once it calls a tool, which may be
+   * never. The stamps are also outside the retention sweep, so "connected"
+   * cannot quietly turn back into "waiting" when old events are pruned.
+   *
+   * Live rows only: an agent its owner disconnected, or an admin revoked, is
+   * not a connected agent, whatever it did before. The key's columns are read
+   * here rather than through the key service because the service has no
+   * single-row read and this question needs only two columns of one row.
+   */
+  async lastAgentUse(userId: string): Promise<AgentUse | null> {
+    const [[agent], [key]] = await Promise.all([
+      this.db
+        .select({ client: agentConnections.clientName, at: agentConnections.lastUsedAt })
+        .from(agentConnections)
+        .where(
+          and(
+            eq(agentConnections.userId, userId),
+            isNull(agentConnections.revokedAt),
+            isNotNull(agentConnections.lastUsedAt),
+          ),
+        )
+        .orderBy(desc(agentConnections.lastUsedAt))
+        .limit(1),
+      this.db
+        .select({ client: externalApiKeys.label, at: externalApiKeys.lastUsedAt })
+        .from(externalApiKeys)
+        .where(
+          and(
+            eq(externalApiKeys.userId, userId),
+            isNull(externalApiKeys.revokedAt),
+            isNotNull(externalApiKeys.lastUsedAt),
+          ),
+        )
+        .orderBy(desc(externalApiKeys.lastUsedAt))
+        .limit(1),
+    ]);
+    const uses = [
+      agent?.at ? { at: agent.at, client: agent.client ?? 'Unnamed agent', kind: 'agent' as const } : null,
+      key?.at ? { at: key.at, client: key.client, kind: 'key' as const } : null,
+    ].filter((u): u is AgentUse => u !== null);
+    if (uses.length === 0) return null;
+    return uses.reduce((newest, u) => (u.at.getTime() > newest.at.getTime() ? u : newest));
+  }
+
   async revokeConnection(id: string, by: 'owner' | 'admin', ownerUserId?: string): Promise<void> {
     const scope = ownerUserId
       ? and(eq(agentConnections.id, id), eq(agentConnections.userId, ownerUserId))!

package/src/modules/audit/agent-connection.routes.ts

@@ -0,0 +1,56 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+import type { IAgentConnectionStatus } from './audit.contract.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId)
+
+const log = logger('audit');
+
+/** What the onboarding reads: connected or not, and — once connected — when, as what, and through which kind of credential. */
+export interface AgentConnectionResponse {
+  connected: boolean;
+  /** The agent's most recent call, ISO 8601. */
+  at?: string;
+  /** The agent's registered client name, or the connection key's label. */
+  client?: string;
+  /**
+   * Which of the two `client` is: `agent` for an OAuth connection's
+   * registered name, `key` for a connection key's free-text label. Only an
+   * `agent` name says which app connected.
+   */
+  kind?: 'agent' | 'key';
+}
+
+/**
+ * GET /api/onboarding/agent-connection — "has an agent of mine reached the
+ * platform yet?", JWT-only (mounted behind the session middleware).
+ *
+ * The connect-your-agent page and the Get set up list ask it once on
+ * arrival, and again when the person comes back to the tab; the moment it
+ * changes is told by the `agent-connected` event the use-stamp paths emit
+ * over the event stream, so nothing asks on a timer. It answers for the
+ * CALLER alone: the user is the token's, and nothing in the request can name
+ * anyone else — there is no parameter to try.
+ *
+ * `no-store` because the answer is expected to change between two asks; a
+ * cached "not yet" would keep a page waiting on an agent that has already
+ * arrived.
+ */
+export function createAgentConnectionRoutes(status: IAgentConnectionStatus): express.Router {
+  const router = express.Router();
+
+  router.get('/onboarding/agent-connection', async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    try {
+      const use = await status.lastAgentUse(req.userId!);
+      const body: AgentConnectionResponse = use
+        ? { connected: true, at: use.at.toISOString(), client: use.client, kind: use.kind }
+        : { connected: false };
+      res.json(body);
+    } catch (err) {
+      log.error('agent connection status failed:', { err });
+      res.status(500).json({ error: 'Could not check your agent' });
+    }
+  });
+
+  return router;
+}

package/src/modules/audit/audit.contract.ts

@@ -121,6 +121,32 @@ export interface IAgentAuditService {
   revokeConnection(id: string, by: 'owner' | 'admin', ownerUserId?: string): Promise<void>;
 }
 
+/**
+ * The most recent use of any of one person's live agents: when, what it
+ * calls itself (the agent's registered client name, or the key's label), and
+ * which of the two that name is.
+ */
+export interface AgentUse {
+  at: Date;
+  client: string;
+  /**
+   * `agent`: an OAuth connection, and `client` is the name the agent
+   * registered. `key`: a connection key, and `client` is whatever label its
+   * owner typed — it says nothing about which app holds the key.
+   */
+  kind: 'agent' | 'key';
+}
+
+/**
+ * The onboarding's "is your agent connected yet?" — answered for ONE person,
+ * from the use stamps the auth paths already write, so it costs two indexed
+ * single-row reads and records nothing new.
+ */
+export interface IAgentConnectionStatus {
+  /** The newest use among the person's live agent connections and connection keys; null when none has been used. */
+  lastAgentUse(userId: string): Promise<AgentUse | null>;
+}
+
 export class AuditPrincipalNotFoundError extends Error {
   constructor() {
     super('No such agent or key');

package/src/modules/audit/index.ts

@@ -2,6 +2,7 @@ export * from './audit.contract.js';
 export { AgentAuditService, MAX_EVENT_PAGE, retentionDaysFrom } from './agent-audit.service.js';
 export { createAgentRestAuditMiddleware } from './agent-rest-audit.middleware.js';
 export { createAuditRoutes } from './audit.routes.js';
+export { createAgentConnectionRoutes, type AgentConnectionResponse } from './agent-connection.routes.js';
 export { RequestAudit } from './request-audit.js';
 export {
   classifyToolCall,

package/src/modules/auth/__tests__/account.routes.test.ts

@@ -67,6 +67,8 @@ describe('account routes — admin gate', () => {
       body: JSON.stringify({ email: 'x@example.com', password: 'long-enough-pw' }),
     });
     expect(create.status).toBe(403);
+    // Not an admission refusal: nothing here may read as "no seat left".
+    expect(await create.json()).toEqual({ error: 'Admins only' });
     expect(authService.createAccount).not.toHaveBeenCalled();
   });
 
@@ -151,7 +153,7 @@ describe('account routes — admin gate', () => {
     expect(accountErasure.eraseUser).toHaveBeenLastCalledWith('u2');
   });
 
-  it('an account the admission port refuses → 403 carrying the port\'s own words', async () => {
+  it('an account the admission port refuses → 403 carrying the port\'s own words, marked as an admission refusal', async () => {
     const base = await listen(makeApp({ admin: true }));
     vi.mocked(authService.createAccount).mockRejectedValueOnce(
       new AccountAdmissionRefusedError('No seat left on this plan'),
@@ -162,7 +164,7 @@ describe('account routes — admin gate', () => {
       body: JSON.stringify({ email: 'b@example.com', password: 'long-enough-pw' }),
     });
     expect(refused.status).toBe(403);
-    expect(((await refused.json()) as { error: string }).error).toBe('No seat left on this plan');
+    expect(await refused.json()).toEqual({ error: 'No seat left on this plan', kind: 'admission' });
   });
 
   it('erasure failure → 500 with a generic body (no internal error text)', async () => {
@@ -370,7 +372,7 @@ describe('account routes — switching an account off and on', () => {
     const base = await listen(makeApp({ admin: true }));
     const res = await post(base, 'u2/reactivate');
     expect(res.status).toBe(403);
-    expect(((await res.json()) as { error: string }).error).toBe('All 3 seats are taken');
+    expect(await res.json()).toEqual({ error: 'All 3 seats are taken', kind: 'admission' });
   });
 
   it('answers a refused deactivation (the deployment admin, say) with 400 and the reason', async () => {

package/src/modules/auth/account.routes.ts

@@ -73,7 +73,13 @@ export function createAccountRoutes(
       const msg = error instanceof Error ? error.message : 'Unknown error';
       // The deployment has no place for the account (a seat limit, say): the
       // port's own words, as a refusal rather than a malformed request.
-      res.status(error instanceof AccountAdmissionRefusedError ? 403 : 400).json({ error: msg });
+      // `kind` tells it apart from `requireAdmin`'s 403, which a caller must
+      // not read as "no seat left".
+      if (error instanceof AccountAdmissionRefusedError) {
+        res.status(403).json({ error: msg, kind: 'admission' });
+        return;
+      }
+      res.status(400).json({ error: msg });
     }
   });
 
@@ -107,7 +113,8 @@ export function createAccountRoutes(
 
   // POST /api/admin/accounts/:userId/reactivate — switch it back on, if the
   // deployment has room: the admission port is asked, as for a new account
-  // (a host that sells seats answers from its plan; 403 with its words).
+  // (a host that sells seats answers from its plan; 403 with its words and
+  // `kind: 'admission'`).
   router.post('/admin/accounts/:userId/reactivate', requireAdmin, async (req, res) => {
     const userId = String(req.params.userId);
     try {
@@ -119,7 +126,7 @@ export function createAccountRoutes(
       res.status(204).end();
     } catch (error) {
       if (error instanceof AccountAdmissionRefusedError) {
-        res.status(403).json({ error: error.message });
+        res.status(403).json({ error: error.message, kind: 'admission' });
         return;
       }
       log.error('switching an account on failed:', { err: error });

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

@@ -30,7 +30,7 @@ export const AUTH_COOKIE_NAME = 'bevel_token';
  * beats the dep surface of a middleware. Returns `null` if the cookie
  * is absent or empty.
  */
-function readAuthCookie(req: Request): string | null {
+export function readAuthCookie(req: Request): string | null {
   const header = req.headers.cookie;
   if (!header) return null;
   for (const segment of header.split(';')) {

package/src/modules/code-mode/__tests__/code-mode.tool.test.ts

@@ -27,6 +27,16 @@ vi.mock('../code-mode-names.js', async (importOriginal) => {
       }
       if (name === 'down.run') throw new Error('repository unavailable: ECONNREFUSED');
       if (name === 'solo.run') return { tool: { name: 'solo.run' }, utcpName: 'solo.run' };
+      if (name === 'kb.read_file') {
+        return {
+          tool: {
+            name: 'kb.read_file',
+            description: 'Read a file.',
+            inputs: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+          },
+          utcpName: 'kb.read_file',
+        };
+      }
       return null;
     }),
   };
@@ -35,7 +45,8 @@ vi.mock('../code-mode-names.js', async (importOriginal) => {
 const { createToolsInfoTool } = await import('../code-mode.tool.js');
 
 const client = {
-  toolToTypeScriptInterface: (tool: { name: string }) => `interface ${tool.name}`,
+  toolToTypeScriptInterface: (tool: { name: string; description?: string }) =>
+    tool.description ? `/** ${tool.description} */ interface ${tool.name}` : `interface ${tool.name}`,
 } as unknown as CodeModeUtcpClient;
 
 type ToolsInfoResult = { interfaces: string; not_found: string[]; errors?: string[] };
@@ -58,11 +69,16 @@ describe('tools_info', () => {
 
   it('omits the errors field entirely when every name resolves or misses cleanly', async () => {
     const result = await run(['solo.run', 'nope']);
-    expect(result.interfaces).toBe('interface solo.run');
+    expect(result.interfaces).toBe('/** Call: solo.run({}) */ interface solo.run');
     expect(result.not_found).toEqual(['nope']);
     expect(result.errors).toBeUndefined();
   });
 
+  it('shows each tool with its Call: line, as the chain description promises', async () => {
+    const result = await run(['kb.read_file']);
+    expect(result.interfaces).toBe('/** Call: kb.read_file({ query: "..." })\n\nRead a file. */ interface kb.read_file');
+  });
+
   it('contains ONLY ambiguity — an outage rethrows instead of posing as partial success', async () => {
     await expect(run(['solo.run', 'down.run'])).rejects.toThrow(/repository unavailable/);
   });