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

package/migrations/meta/_journal.json

@@ -85,6 +85,20 @@
       "when": 1789903776474,
       "tag": "0011_plugin_join_request_claim",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1790179003112,
+      "tag": "0012_agent_audit",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1790243482866,
+      "tag": "0013_agent_identity_and_key_soft_delete",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,8 +52,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.19.0",
-    "@bevel-software/platform-shared": "0.19.0"
+    "@bevel-software/platform-mcp-core": "0.20.0",
+    "@bevel-software/platform-shared": "0.20.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",
@@ -79,7 +79,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:live": "vitest run .live.test",

package/src/core/create-core-server.ts

@@ -52,6 +52,9 @@ import { createGroupsAdminRoutes } from '../modules/access/groups-admin.routes.j
 import { createUpdateCheckRoutes } from '../modules/update-check/update-check.routes.js';
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
 import { createConnectionKeysAdminRoutes } from '../modules/tool-auth/connection-keys-admin.routes.js';
+import { createAuditRoutes } from '../modules/audit/audit.routes.js';
+import { createAgentRestAuditMiddleware } from '../modules/audit/agent-rest-audit.middleware.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../modules/tool-manuals/tool-manuals.contract.js';
 import { createSetupRoutes } from '../modules/settings/setup.routes.js';
 import { oidcRedirectUri } from '../modules/auth/oidc-auth-provider.js';
 import { repositoryConnectionCheck } from '../modules/settings/connection-check.js';
@@ -479,6 +482,24 @@ export async function createCoreServer(
   const toolsRouter = express.Router();
   const ta = core.toolAuthMiddleware;
   const th = core.toolHandlerFactory;
+  // The Audit log's recorder for the REST tool calls the LOCAL server makes
+  // directly (its skill reads, above all) — judged on `finish`, after each
+  // route's own auth has run, and only for the exchanged grant that names an
+  // agent connection, so nothing the hosted proxy already records is counted
+  // twice. Ahead of every tool route, on the same router.
+  toolsRouter.use(
+    '/agent/tools/:name',
+    createAgentRestAuditMiddleware({
+      recorder: core.agentAuditService,
+      kbManualName: EXTERNAL_KB_MANUAL_NAME,
+      skillFolders: async (userId) => {
+        const user = await core.authService.getUserById(userId);
+        if (!user) return [];
+        const skills = await core.skillService.listSkills(user.email);
+        return skills.map((s) => ({ name: s.name, path: s.path }));
+      },
+    }),
+  );
   // Shared ontology-session boundary gate config, consumed by every tool
   // surface that touches the KB (file tools + graph tools). The gate's
   // blocking decision runs through the workflow hooks: core registers none
@@ -729,6 +750,13 @@ export async function createCoreServer(
     core.authMiddleware,
     createConnectionKeysAdminRoutes(core.externalApiKeyService, core.adminAccess),
   );
+  // The Audit log: a person's agents and keys with what they called (admins:
+  // everyone's), and the revoke of either — owner- or admin-gated inside.
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createAuditRoutes(core.agentAuditService, core.externalApiKeyService, core.adminAccess),
+  );
   // First-run setup. Mounted with the other authed routes but touching NO
   // workspace — it has to work on a deployment that has no knowledge base yet,
   // which is the whole reason it exists. The startup runner rides along for

package/src/core/create-core-services.ts

@@ -130,6 +130,7 @@ import {
 } from '../modules/tool-auth/tool-auth.middleware.js';
 import { unmeteredLlmUsage, type ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
 import { McpService } from '../modules/mcp/mcp.service.js';
+import { AgentAuditService, retentionDaysFrom } from '../modules/audit/agent-audit.service.js';
 import { readAgentPreamble, type AgentPreambleReader } from '../modules/agent-instructions/index.js';
 import { createMcpAuthMiddleware } from '../modules/mcp/mcp-auth.middleware.js';
 import { BevelOAuthProvider } from '../modules/mcp/oauth/bevel-oauth-provider.js';
@@ -284,6 +285,8 @@ export interface CoreServices {
    * advertise the same pointer the auth middleware does.
    */
   mcpResourceMetadataUrl: string;
+  /** The Audit log: what every connected agent and key called, and the revoke of an agent's grant. */
+  agentAuditService: AgentAuditService;
   toolRegistry: ToolRegistry;
   toolAuthMiddleware: ReturnType<typeof createToolAuthMiddleware>;
   manualAuthMiddleware: ReturnType<typeof createManualAuthMiddleware>;
@@ -915,6 +918,13 @@ export async function createCoreServices(
   // the proxy below composes in-process per request; the agent-facing route
   // serves the same composition to the local bridge and the frontend card.
   const readPreamble: AgentPreambleReader = () => readAgentPreamble(workspaceService, kbDirName, disk);
+  // The Audit log. Records through the proxy below (every call an external
+  // agent makes), reads keys through the key service so their shape is
+  // defined once, and prunes past the retention setting — read per sweep, so
+  // a change on the Deployment page applies without a restart.
+  const agentAuditService = new AgentAuditService(db, externalApiKeyService, () =>
+    retentionDaysFrom(settings.resolve('auditRetentionDays')),
+  );
   const mcpService = new McpService(
     {
       // Loopback to our own REST tool surface — 127.0.0.1 (not localhost) to pin
@@ -942,6 +952,8 @@ export async function createCoreServices(
     // provider is constructed just below (it needs nothing from McpService;
     // the binding is only dereferenced at call time, long after boot).
     (bearer) => mcpOAuthProvider.revokeByAccessToken(bearer),
+    // Every attributable call lands in the Audit log through this.
+    agentAuditService,
   );
   // A changed secret invalidates what the proxy built from the old value for
   // that user (null = shared secret → everyone): remembered manual failures,
@@ -1194,6 +1206,7 @@ export async function createCoreServices(
     mcpAuthMiddleware,
     mcpOAuthProvider,
     mcpResourceMetadataUrl,
+    agentAuditService,
     toolRegistry,
     toolAuthMiddleware,
     manualAuthMiddleware,

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

@@ -0,0 +1,370 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- the fake drizzle chain below is untyped by design, like its siblings */
+import { describe, expect, it, vi } from 'vitest';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import { AgentAuditService, retentionDaysFrom } from '../agent-audit.service.js';
+import { AuditPrincipalNotFoundError, InvalidCursorError } from '../audit.contract.js';
+import type { Database } from '../../database/connection.js';
+import { agentConnections, oauthTokens } from '../../database/schema.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+
+/**
+ * The fake drizzle chain the other service tests use: every chainable method
+ * returns the chain, the chain is thenable, and each `db.insert / select /
+ * 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.
+ */
+function makeFakeDb(queue: unknown[]) {
+  const captured: { values: any[]; set: any[]; where: SQL[]; updateTargets: unknown[] } = {
+    values: [],
+    set: [],
+    where: [],
+    updateTargets: [],
+  };
+  const counts = { insert: 0, select: 0, update: 0, delete: 0 };
+
+  function nextChain() {
+    const result = queue.shift();
+    const chain: any = {};
+    const passthrough = (recorder?: (args: any[]) => void) =>
+      vi.fn((...args: any[]) => {
+        recorder?.(args);
+        return chain;
+      });
+    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.innerJoin = passthrough();
+    chain.from = passthrough();
+    chain.orderBy = passthrough();
+    chain.groupBy = passthrough();
+    chain.returning = passthrough();
+    chain.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR);
+    return chain;
+  }
+
+  const db: any = {
+    insert: vi.fn(() => (counts.insert++, nextChain())),
+    select: vi.fn(() => (counts.select++, nextChain())),
+    update: vi.fn((table: unknown) => (counts.update++, captured.updateTargets.push(table), nextChain())),
+    delete: vi.fn(() => (counts.delete++, nextChain())),
+    transaction: vi.fn((fn: (tx: any) => Promise<unknown>) => fn(db)),
+  };
+  return { db: db as Database, captured, counts };
+}
+
+/** A captured predicate as the SQL it would send, with its parameters. */
+function render(fragment: SQL | undefined): { sql: string; params: unknown[] } {
+  if (!fragment) return { sql: '', params: [] };
+  const q = new PgDialect().sqlToQuery(fragment);
+  return { sql: q.sql, params: q.params };
+}
+
+const ALICE = { id: 'u-alice', email: 'alice@example.com', name: 'Alice' };
+const BOB = { id: 'u-bob', email: 'bob@example.com', name: 'Bob' };
+const DAY = 24 * 60 * 60_000;
+const NOW = Date.UTC(2026, 8, 23, 12, 0, 0);
+
+const key = (over: object) => ({
+  id: 'k-1',
+  label: 'CI pipeline',
+  kind: 'key',
+  createdAt: NOW - 10 * DAY,
+  lastUsedAt: NOW - DAY,
+  revokedAt: null,
+  revokedBy: null,
+  ...over,
+});
+const connection = (over: object) => ({
+  id: 'c-1',
+  userId: ALICE.id,
+  clientId: 'client-claude',
+  clientName: 'Claude',
+  connectedAt: new Date(NOW - 5 * DAY),
+  lastUsedAt: new Date(NOW - 60_000),
+  revokedAt: null,
+  revokedBy: null,
+  ...over,
+});
+
+function makeService(queue: unknown[], keys: Partial<IExternalApiKeyService> = {}, retention: number | null = 90) {
+  const fake = makeFakeDb(queue);
+  const keyService = {
+    listForUser: vi.fn(async () => []),
+    listForDeployment: vi.fn(async () => []),
+    ownerOf: vi.fn(async () => null),
+    ...keys,
+  } as unknown as IExternalApiKeyService;
+  const service = new AgentAuditService(fake.db, keyService, () => retention, () => NOW);
+  return { service, ...fake, keyService };
+}
+
+/** Let the fire-and-forget insert (and whatever it schedules) settle. */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+describe('AgentAuditService.record', () => {
+  it('inserts the event with exactly one principal column set and never throws to the caller', async () => {
+    const { service, captured } = makeService([undefined /* insert */]);
+    service.record({
+      userId: ALICE.id,
+      principal: { kind: 'key', id: 'k-1' },
+      kind: 'tool',
+      manual: 'notion',
+      name: 'search',
+      outcome: 'ok',
+      durationMs: 42,
+    });
+    await flush();
+    expect(captured.values[0]).toMatchObject({
+      userId: ALICE.id,
+      keyId: 'k-1',
+      connectionId: null,
+      kind: 'tool',
+      manual: 'notion',
+      name: 'search',
+      outcome: 'ok',
+      durationMs: 42,
+    });
+
+    const agent = makeService([undefined]);
+    agent.service.record({
+      userId: ALICE.id,
+      principal: { kind: 'agent', id: 'c-1' },
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+      outcome: 'ok',
+      durationMs: null,
+    });
+    await flush();
+    expect(agent.captured.values[0]).toMatchObject({ keyId: null, connectionId: 'c-1', kind: 'skill' });
+  });
+
+  it('prunes past the retention window once per hour, not on every insert', async () => {
+    const { service, counts } = makeService([undefined, undefined, undefined, undefined], {}, 30);
+    const event = {
+      userId: ALICE.id,
+      principal: { kind: 'key' as const, id: 'k-1' },
+      kind: 'capability' as const,
+      manual: null,
+      name: 'read_file',
+      outcome: 'ok' as const,
+      durationMs: 3,
+    };
+    service.record(event);
+    await flush();
+    expect(counts.delete).toBe(1); // the first insert sweeps
+    service.record(event);
+    await flush();
+    expect(counts.delete).toBe(1); // the second, a moment later, does not
+  });
+
+  it('sweeps nothing on a deployment that keeps events forever', async () => {
+    const { service, counts } = makeService([undefined], {}, null);
+    service.record({
+      userId: ALICE.id,
+      principal: { kind: 'key', id: 'k-1' },
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+      outcome: 'ok',
+      durationMs: 3,
+    });
+    await flush();
+    expect(counts.delete).toBe(0);
+  });
+
+  it('swallows an insert failure (logged), so a tool result never fails over its bookkeeping', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { service } = makeService([Promise.reject(new Error('db down'))]);
+    expect(() =>
+      service.record({
+        userId: ALICE.id,
+        principal: { kind: 'key', id: 'k-1' },
+        kind: 'capability',
+        manual: null,
+        name: 'ask',
+        outcome: 'ok',
+        durationMs: 1,
+      }),
+    ).not.toThrow();
+    await flush();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe('AgentAuditService.listPrincipals', () => {
+  it("lists a person's keys and agents with event counts, live first, most recently used first", async () => {
+    const { service } = makeService(
+      [
+        // keysForUser: the user row
+        [ALICE],
+        // connections joined with users
+        [
+          { connection: connection({ id: 'c-old', revokedAt: new Date(NOW - DAY), revokedBy: 'owner', lastUsedAt: new Date(NOW) }), user: ALICE },
+          { connection: connection({ id: 'c-1' }), user: ALICE },
+        ],
+        // event counts
+        [
+          { keyId: 'k-1', connectionId: null, n: 7 },
+          { keyId: null, connectionId: 'c-1', n: 3 },
+        ],
+      ],
+      { listForUser: vi.fn(async () => [key({ lastUsedAt: NOW - 2 * DAY })]) },
+    );
+
+    const rows = await service.listPrincipals({ userId: ALICE.id });
+
+    expect(rows.map((r) => `${r.kind}:${r.id}`)).toEqual(['agent:c-1', 'key:k-1', 'agent:c-old']);
+    expect(rows[0]).toMatchObject({ label: 'Claude', eventCount: 3, user: ALICE, revokedAt: null });
+    expect(rows[1]).toMatchObject({ label: 'CI pipeline', keyKind: 'key', eventCount: 7, user: ALICE });
+    // The revoked one sinks, still carrying who ended it and its (zero) count.
+    expect(rows[2]).toMatchObject({ revokedBy: 'owner', eventCount: 0 });
+  });
+
+  it('lists every account for the deployment, grouped by owner email', async () => {
+    const { service, keyService } = makeService(
+      [
+        [{ connection: connection({ id: 'c-bob', userId: BOB.id }), user: BOB }],
+        [],
+      ],
+      { listForDeployment: vi.fn(async () => [{ ...key({}), user: ALICE }]) },
+    );
+
+    const rows = await service.listPrincipals('all');
+
+    expect(rows.map((r) => r.user.email)).toEqual(['alice@example.com', 'bob@example.com']);
+    expect((keyService.listForDeployment as any)).toHaveBeenCalled();
+    expect((keyService.listForUser as any)).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentAuditService.listEvents', () => {
+  const eventId = (i: number) => `00000000-0000-4000-8000-00000000000${i}`;
+  const eventRow = (i: number) => ({
+    id: eventId(i),
+    kind: 'capability',
+    manual: null,
+    name: `tool-${i}`,
+    outcome: 'ok',
+    at: new Date(NOW - i * 1000),
+  });
+
+  it('pages newest first with a keyset cursor and reports the total', async () => {
+    const { service, captured } = makeService([
+      [eventRow(1), eventRow(2), eventRow(3)] /* limit 2 → 3 rows means more */,
+      [{ total: 12 }],
+    ]);
+
+    const page = await service.listEvents({ kind: 'key', id: 'k-1' }, { limit: 2 });
+
+    expect(page.events.map((e) => e.id)).toEqual([eventId(1), eventId(2)]);
+    expect(page.events[0]).toMatchObject({ kind: 'capability', name: 'tool-1', outcome: 'ok', at: NOW - 1000 });
+    expect(page.total).toBe(12);
+    expect(page.nextCursor).toBe(`${NOW - 2000}.${eventId(2)}`);
+    // The page and the total both read THIS principal's rows and nobody else's.
+    expect(render(captured.where[0]).params).toEqual(['k-1']);
+    expect(render(captured.where[1]).params).toEqual(['k-1']);
+
+    // A cursor page counts nothing: the reader holds the first page's total.
+    const last = makeService([[eventRow(3)]]);
+    const tail = await last.service.listEvents({ kind: 'key', id: 'k-1' }, { before: page.nextCursor!, limit: 2 });
+    expect(tail.events.map((e) => e.id)).toEqual([eventId(3)]);
+    expect(tail.nextCursor).toBeNull();
+    expect(tail.total).toBeNull();
+    expect(last.counts.select).toBe(1);
+    // The cursor became the keyset predicate: strictly older, or the same
+    // instant and a smaller id.
+    const after = render(last.captured.where[0]);
+    expect(after.sql).toMatch(/"at" < \$2 or \("agent_events"."at" = \$3 and "agent_events"."id" < \$4\)/);
+    // The instant rides twice (strictly-older, and same-instant) as whatever
+    // the driver spells a timestamp as; the id is the cursor's own.
+    expect(after.params[0]).toBe('k-1');
+    expect(after.params[1]).toEqual(after.params[2]);
+    expect(new Date(after.params[1] as string | Date).getTime()).toBe(NOW - 2000);
+    expect(after.params[3]).toBe(eventId(2));
+  });
+
+  it('refuses a cursor it did not issue instead of sending it to the database', async () => {
+    const { service, counts } = makeService([]);
+    for (const before of ['123.bad', 'notanumber.' + eventId(1), '1e5.' + eventId(1), eventId(1)]) {
+      await expect(service.listEvents({ kind: 'key', id: 'k-1' }, { before, limit: 2 })).rejects.toBeInstanceOf(
+        InvalidCursorError,
+      );
+    }
+    expect(counts.select).toBe(0);
+  });
+});
+
+describe('AgentAuditService.ownerOf', () => {
+  it('answers for a key through the key service, and for an agent from its connection row', async () => {
+    const { service, keyService } = makeService([[{ userId: BOB.id }]], { ownerOf: vi.fn(async () => ALICE.id) });
+    await expect(service.ownerOf({ kind: 'key', id: 'k-1' })).resolves.toBe(ALICE.id);
+    expect(keyService.ownerOf).toHaveBeenCalledWith('k-1');
+    await expect(service.ownerOf({ kind: 'agent', id: 'c-1' })).resolves.toBe(BOB.id);
+  });
+});
+
+describe('AgentAuditService.revokeConnection', () => {
+  it('marks the connection revoked by whom, and revokes every live token it holds', async () => {
+    const { service, captured } = makeService([
+      [{ id: 'c-1' }] /* connection update.returning */,
+      undefined /* tokens update */,
+    ]);
+
+    await service.revokeConnection('c-1', 'admin');
+
+    expect(captured.updateTargets).toEqual([agentConnections, oauthTokens]);
+    expect(captured.set[0]).toMatchObject({ revokedBy: 'admin' });
+    expect(captured.set[0].revokedAt).toBeInstanceOf(Date);
+    expect(captured.set[1].revokedAt).toBeInstanceOf(Date);
+    // An admin's revoke is unscoped by owner, and touches only a LIVE connection…
+    const connection = render(captured.where[0]);
+    expect(connection.sql).toMatch(/"agent_connections"."id" = \$1 and "agent_connections"."revoked_at" is null/);
+    expect(connection.params).toEqual(['c-1']);
+    // …and exactly its own live tokens, never another connection's.
+    const tokens = render(captured.where[1]);
+    expect(tokens.sql).toMatch(/"oauth_tokens"."connection_id" = \$1 and "oauth_tokens"."revoked_at" is null/);
+    expect(tokens.params).toEqual(['c-1']);
+  });
+
+  it("scopes an owner's revoke to their own connections", async () => {
+    const { service, captured } = makeService([[{ id: 'c-1' }], undefined]);
+    await service.revokeConnection('c-1', 'owner', ALICE.id);
+    const connection = render(captured.where[0]);
+    expect(connection.sql).toMatch(/"agent_connections"."user_id" = \$2/);
+    expect(connection.params).toEqual(['c-1', ALICE.id]);
+    expect(captured.set[0]).toMatchObject({ revokedBy: 'owner' });
+  });
+
+  it('is idempotent on an already-revoked connection and throws for one out of scope', async () => {
+    const already = makeService([[] /* nothing live */, [{ id: 'c-1' }] /* but it exists */]);
+    await expect(already.service.revokeConnection('c-1', 'owner', ALICE.id)).resolves.toBeUndefined();
+    expect(already.counts.update).toBe(1); // no token revoke on a no-op
+    // The existence probe carries the SAME owner scope as the revoke itself.
+    expect(render(already.captured.where[1]).params).toEqual(['c-1', ALICE.id]);
+
+    const foreign = makeService([[], []]);
+    await expect(foreign.service.revokeConnection('c-1', 'owner', BOB.id)).rejects.toBeInstanceOf(
+      AuditPrincipalNotFoundError,
+    );
+  });
+});
+
+describe('retentionDaysFrom', () => {
+  it('reads a positive whole number of days, and blank, zero or negative as forever', () => {
+    expect(retentionDaysFrom('30')).toBe(30);
+    expect(retentionDaysFrom(' 3650 ')).toBe(3650);
+    expect(retentionDaysFrom('99999')).toBe(99999);
+    expect(retentionDaysFrom('')).toBeNull();
+    expect(retentionDaysFrom('0')).toBeNull();
+    expect(retentionDaysFrom('-5')).toBeNull();
+    // Not a window at all: kept forever too, and said once on the log.
+    expect(retentionDaysFrom('1.5')).toBeNull();
+    expect(retentionDaysFrom('lots')).toBeNull();
+  });
+});

package/src/modules/audit/__tests__/agent-rest-audit.middleware.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAgentRestAuditMiddleware } from '../agent-rest-audit.middleware.js';
+import type { AgentEventInput } from '../audit.contract.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+
+const KB = 'KNOWLEDGE_BASE';
+
+/**
+ * The REST recorder, on a real router: a stand-in auth stamps whatever
+ * `toolAuth` a test wants (the way the real gate does, per route), a couple
+ * of routes answer as the platform tools do, and the recorder is watched.
+ */
+function makeApp(auth: ToolAuth | null, skills: { name: string; path: string }[] = []) {
+  const events: AgentEventInput[] = [];
+  const skillFolders = vi.fn(async () => skills);
+  const app = express();
+  app.use(express.json());
+  const router = express.Router();
+  router.use(
+    '/agent/tools/:name',
+    createAgentRestAuditMiddleware({ recorder: { record: (e) => void events.push(e) }, kbManualName: KB, skillFolders }),
+  );
+  const stampAuth: express.RequestHandler = (req, res, next) => {
+    if (!auth) {
+      res.status(401).json({ error: 'nope' });
+      return;
+    }
+    req.toolAuth = auth;
+    next();
+  };
+  router.post('/agent/tools/get_skill', stampAuth, (_req, res) => res.json({ ok: true }));
+  router.post('/agent/tools/read_file', stampAuth, (_req, res) => res.json({ content: 'x' }));
+  router.post('/agent/tools/list_skills', stampAuth, (_req, res) => res.json({ skills }));
+  router.post('/agent/tools/boom', stampAuth, (_req, res) => res.status(500).json({ error: 'kaboom' }));
+  app.use('/api', router);
+  return { app, events, skillFolders };
+}
+
+let server: Server;
+afterEach(() => server?.close());
+
+async function listen(app: express.Express): Promise<string> {
+  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}`;
+}
+
+const post = (base: string, name: string, body: unknown) =>
+  fetch(`${base}/api/agent/tools/${name}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+/** Recording lands after the response; give it a turn. */
+const settle = () => new Promise((r) => setTimeout(r, 20));
+
+const EXCHANGED_GRANT: ToolAuth = { source: 'external', userId: 'u-1', connectionId: 'conn-1', scope: 'write' };
+
+describe('the REST recorder for the local server', () => {
+  it("records a skill read made with an exchanged grant as that agent's skill event, with the outcome", async () => {
+    const { app, events } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
+    const base = await listen(app);
+    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(200);
+    expect((await post(base, 'boom', {})).status).toBe(500);
+    await settle();
+    expect(events).toEqual([
+      expect.objectContaining({
+        userId: 'u-1',
+        principal: { kind: 'agent', id: 'conn-1' },
+        kind: 'skill',
+        manual: 'Plugins/Sales/rfi',
+        name: 'rfi',
+        outcome: 'ok',
+      }),
+      expect.objectContaining({ kind: 'capability', name: 'boom', outcome: 'error' }),
+    ]);
+    expect(typeof events[0]!.durationMs).toBe('number');
+  });
+
+  it('fetches the skill catalog only for a read that names a path, and classifies the read by it', async () => {
+    const { app, events, skillFolders } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
+    const base = await listen(app);
+    await post(base, 'list_skills', {});
+    await post(base, 'read_file', { path: 'Plugins/Sales/rfi/SKILL.md', branch: 'main' });
+    await settle();
+    expect(skillFolders).toHaveBeenCalledTimes(1);
+    expect(events.map((e) => `${e.kind}:${e.name}`)).toEqual(['capability:list_skills', 'skill:rfi']);
+  });
+
+  it('records nothing for a connection key, a loopback token, or a refused call — those are the proxy\'s to record, or nobody\'s', async () => {
+    const key = makeApp({ source: 'external', userId: 'u-1', tokenId: 'k-1', scope: 'write' });
+    let base = await listen(key.app);
+    await post(base, 'get_skill', { name: 'rfi' });
+    server.close();
+    const loopback = makeApp({ source: 'external', userId: 'u-1', scope: 'write' });
+    base = await listen(loopback.app);
+    await post(base, 'get_skill', { name: 'rfi' });
+    server.close();
+    const refused = makeApp(null);
+    base = await listen(refused.app);
+    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(401);
+    await settle();
+    expect(key.events).toEqual([]);
+    expect(loopback.events).toEqual([]);
+    expect(refused.events).toEqual([]);
+  });
+});