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

package/src/modules/mcp/__tests__/mcp-auth.middleware.test.ts

@@ -48,6 +48,8 @@ function makeExternalApiKeyService(
 
 function makeOAuthProvider(
   verify?: (t: string) => Promise<{ extra?: Record<string, unknown> }>,
+  /** Whether an agent connection still admits requests — true unless a test says otherwise. */
+  live?: (connectionId: string) => Promise<boolean>,
 ) {
   return {
     looksLikeAccessToken: (t: string) => typeof t === 'string' && t.startsWith('bevel-mcp_'),
@@ -57,6 +59,8 @@ function makeOAuthProvider(
           throw new InvalidTokenError('unknown token');
         }),
     ),
+    isConnectionLive: vi.fn(live ?? (async () => true)),
+    noteConnectionUse: vi.fn(),
   } as unknown as BevelOAuthProvider;
 }
 
@@ -179,7 +183,7 @@ describe('createMcpAuthMiddleware', () => {
     const auth = makeAuthService();
     const externalApiKeys = makeExternalApiKeyService();
     const oauth = makeOAuthProvider(async () => ({
-      extra: { userId: 'user-5', userEmail: 'eve@example.com' },
+      extra: { userId: 'user-5', userEmail: 'eve@example.com', connectionId: 'conn-5' },
     }));
     const mw = makeMw({ auth, keys: externalApiKeys, oauth });
     const { req, res, next } = makeReqRes('Bearer bevel-mcp_token123');
@@ -188,14 +192,28 @@ describe('createMcpAuthMiddleware', () => {
 
     expect(req.userId).toBe('user-5');
     expect(req.userEmail).toBe('eve@example.com');
-    // OAuth sessions are unmetered like JWT sessions — no connection key id.
+    // OAuth sessions are unmetered like JWT sessions — no connection key id…
     expect(req.externalApiKeyId).toBeUndefined();
+    // …but they ARE attributed to the agent behind the grant, for the Audit log.
+    expect(req.agentConnectionId).toBe('conn-5');
     expect(next).toHaveBeenCalled();
     // Neither the connection-key nor the JWT path may see this token shape.
     expect((externalApiKeys as any).verifyAndLoadToken).not.toHaveBeenCalled();
     expect((auth as any).verifyToken).not.toHaveBeenCalled();
   });
 
+  it('binds no agent for an OAuth token minted before connections existed, and still admits it', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5', userEmail: 'eve@example.com', connectionId: null },
+    }));
+    const mw = makeMw({ oauth });
+    const { req, res, next } = makeReqRes('Bearer bevel-mcp_token123');
+    await mw(req, res, next);
+    expect(req.userId).toBe('user-5');
+    expect(req.agentConnectionId).toBeUndefined();
+    expect(next).toHaveBeenCalled();
+  });
+
   it('401s with the discovery challenge when the OAuth token is invalid/expired/revoked', async () => {
     const mw = makeMw();
     const { req, res, next, setHeader, status } = makeReqRes('Bearer bevel-mcp_expired');
@@ -276,6 +294,46 @@ describe('createMcpAuthMiddleware', () => {
       expect(next).toHaveBeenCalled();
       expect(req.userId).toBe('user-7');
       expect(req.userEmail).toBe('seven@example.com');
+      // A plain loopback identity names no agent.
+      expect(req.agentConnectionId).toBeUndefined();
+    });
+
+    it('carries the agent connection of an exchanged grant, so the local server stays attributed', async () => {
+      const token = internal.mint({ userId: 'user-7', externalProxy: true, connectionId: 'conn-7' }, 60_000);
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      const oauth = makeOAuthProvider();
+      const mw = makeMw({ internal, auth, oauth });
+      const { req, res, next } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).toHaveBeenCalled();
+      expect(req.agentConnectionId).toBe('conn-7');
+      // Every request through the exchanged grant asks whether the
+      // connection still admits one, and counts as a use of it.
+      expect((oauth as any).isConnectionLive).toHaveBeenCalledWith('conn-7');
+      expect((oauth as any).noteConnectionUse).toHaveBeenCalledWith('conn-7');
+    });
+
+    it('401s an exchanged grant whose agent connection was revoked — the token is stateless, the connection is not', async () => {
+      const token = internal.mint({ userId: 'user-7', externalProxy: true, connectionId: 'conn-7' }, 60_000);
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      const oauth = makeOAuthProvider(undefined, async () => false);
+      const mw = makeMw({ internal, auth, oauth });
+      const { req, res, next, status, setHeader } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).not.toHaveBeenCalled();
+      expect(status).toHaveBeenCalledWith(401);
+      expect(setHeader).toHaveBeenCalledWith('WWW-Authenticate', expect.stringContaining('resource_metadata'));
+      expect(req.agentConnectionId).toBeUndefined();
+      // A refused request is no use of the connection.
+      expect((oauth as any).noteConnectionUse).not.toHaveBeenCalled();
     });
 
     it('401s an expired internal token', async () => {

package/src/modules/mcp/__tests__/mcp.routes.local-token.test.ts

@@ -74,7 +74,7 @@ async function exchange(baseUrl: string, authorization?: string): Promise<Respon
 describe('POST /mcp/local-token', () => {
   it('exchanges a valid OAuth access token for an internal token with the loopback identity + TTL', async () => {
     const oauth = makeOAuthProvider(async () => ({
-      extra: { userId: 'user-5', userEmail: 'eve@example.com' },
+      extra: { userId: 'user-5', userEmail: 'eve@example.com', connectionId: 'conn-9' },
       // A grant with plenty of life left: the loopback constant is the binding cap.
       expiresAt: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
     }));
@@ -88,21 +88,41 @@ describe('POST /mcp/local-token', () => {
     // above outlives it, so the constant is the cap that binds.
     expect(body.expiresInMs).toBe(MCP_LOOPBACK_TOKEN_TTL_MS);
     // The minted token verifies to the resolved user with the externalProxy
-    // flag — identical shape to the hosted session's loopback bearer.
-    expect(internalTokens.verify(body.token)).toEqual({ userId: 'user-5', externalProxy: true });
+    // flag — identical shape to the hosted session's loopback bearer — plus
+    // the grant's agent connection, so the local server's calls stay
+    // attributed to that agent in the Audit log.
+    expect(internalTokens.verify(body.token)).toEqual({
+      userId: 'user-5',
+      externalProxy: true,
+      connectionId: 'conn-9',
+    });
     // …and the tool-auth verifier resolves it to source 'external', exactly
     // how /api/agent/* will treat the local server.
     const verify = createTokenVerifier(
       { looksLikeExternalApiKey: () => false } as unknown as IExternalApiKeyService,
       internalTokens,
     );
+    // …carrying the agent connection, which the REST recorder attributes
+    // the local server's direct tool calls to.
     await expect(verify(body.token)).resolves.toEqual({
       ok: true,
-      auth: { source: 'external', userId: 'user-5', scope: 'write' },
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', scope: 'write' },
     });
     expect((oauth as any).verifyAccessToken).toHaveBeenCalledWith('bevel-mcp_valid123');
   });
 
+  it('mints without a connection claim for a grant that carries none (a token from before connections existed)', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5', userEmail: 'eve@example.com' },
+      expiresAt: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
+    }));
+    const { baseUrl, internalTokens } = await mount(oauth);
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_valid123');
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { token: string };
+    expect(internalTokens.verify(body.token)).toEqual({ userId: 'user-5', externalProxy: true });
+  });
+
   /**
    * The binding that keeps the exchange from OUTLIVING its grant: an access
    * token with less life left than the loopback constant caps the minted

package/src/modules/mcp/__tests__/mcp.routes.stateless.test.ts

@@ -108,7 +108,7 @@ describe('POST /mcp (stateless)', () => {
     expect((await messagesOf(res))[0].result.serverInfo.name).toBe('stub');
     // The messages reach the service, so it can tell an initialize apart.
     expect(mcpService.createRequestServer).toHaveBeenCalledWith(
-      { userId: 'user-A', tokenId: null, bearer: '' },
+      { userId: 'user-A', tokenId: null, connectionId: null, bearer: '' },
       INITIALIZE,
     );
   });

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

@@ -12,6 +12,7 @@ import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { toolDef } from '../../tool-helpers/tool-def.js';
 import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../../agent-instructions/index.js';
+import type { AgentEventInput, IAgentEventRecorder } from '../../audit/audit.contract.js';
 
 /**
  * End-to-end proxy test: a real express app serving the registry-driven tool
@@ -43,6 +44,10 @@ async function setup(deps?: {
   readAgentPreamble?: () => Promise<string | null>;
   /** Extra echo tools to register under these names (the four KB tools, in the prefix tests). */
   extraTools?: string[];
+  /** The Audit log's recorder, when a test watches what gets recorded. */
+  auditRecorder?: IAgentEventRecorder;
+  /** The agent connection an OAuth caller arrived through (with `tokenId: null`). */
+  connectionId?: string | null;
 }) {
   const registry = new ToolRegistry();
   registry.registerExternalTool(
@@ -91,6 +96,16 @@ async function setup(deps?: {
     res.json({ text: `echo: ${b.prompt}`, sessionId: typeof b.sessionId === 'string' ? b.sessionId : 'new-sess' });
   });
   app.post('/api/agent/tools/boom', (_req, res) => res.status(500).json({ error: 'kaboom' }));
+  // The two the Audit log's skill classification reads through: a catalog of
+  // one skill, and a file read that answers for any path (registered as
+  // tools only by the tests that need them, via `extraTools`).
+  app.post('/api/agent/tools/list_skills', (_req, res) =>
+    res.json({ skills: [{ name: 'rfi', description: 'RFI answers', path: 'Plugins/Sales/rfi' }] }),
+  );
+  app.post('/api/agent/tools/read_file', (req, res) => {
+    const b = (req.body ?? {}) as { path?: string };
+    res.json({ content: `contents of ${b.path}` });
+  });
   // A live UTCP manual a catalog entry can point at — one tool, dispatched back
   // to the echo above. Mounted always (it costs one route) so a test can add a
   // MANUAL to the served catalog, not merely a tool to the registry: what a
@@ -149,10 +164,11 @@ async function setup(deps?: {
     deps?.toolManuals as any,
     undefined, // internalTokens — the fake loopback here accepts any bearer
     deps?.revokeOAuthAccess,
+    deps?.auditRecorder,
   );
   lastService = mcp;
   const tokenId = deps?.tokenId === undefined ? 'tok-1' : deps.tokenId;
-  return connectClient(mcp, tokenId);
+  return connectClient(mcp, tokenId, deps?.connectionId ?? null);
 }
 
 /** The service `setup` built last — for a test that needs a SECOND request against the same service. */
@@ -165,9 +181,9 @@ let lastService: McpService | undefined;
  * The initialize message is passed so the server carries instructions,
  * exactly as the route's initialize request would.
  */
-async function connectClient(mcp: McpService, tokenId: string | null): Promise<Client> {
+async function connectClient(mcp: McpService, tokenId: string | null, connectionId: string | null = null): Promise<Client> {
   const server = await mcp.createRequestServer(
-    { userId: 'user-A', tokenId, bearer: 'bevel_testkey' },
+    { userId: 'user-A', tokenId, connectionId, bearer: 'bevel_testkey' },
     { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test-client', version: '0.0.0' } } },
   );
 
@@ -680,3 +696,104 @@ describe('McpService — a collision ends when its sibling is renamed away', ()
     expect(survivor.some((m) => m.startsWith('[mcp] skipping manual "notion-eu": ') && !m.includes('rewrites to'))).toBe(true);
   });
 });
+
+describe('McpService — the Audit log records what an agent calls', () => {
+  /** A recorder that keeps every event, and the same thing as the proxy's collaborator type. */
+  function spyRecorder(): IAgentEventRecorder & { events: AgentEventInput[] } {
+    const events: AgentEventInput[] = [];
+    return { events, record: (e) => void events.push(e) };
+  }
+  const text = (res: Awaited<ReturnType<Client['callTool']>>) => (res.content as Array<{ text: string }>)[0].text;
+  // Recording is fire-and-forget behind the call; give the microtasks a turn.
+  const settle = () => new Promise((r) => setTimeout(r, 10));
+
+  it('records a direct platform tool call as a hexis capability under the connection key, with its outcome', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder });
+
+    await client.callTool({ name: 'ask', arguments: { body: { prompt: 'hello' } } });
+    await client.callTool({ name: 'boom', arguments: {} });
+    await settle();
+
+    expect(recorder.events).toHaveLength(2);
+    expect(recorder.events[0]).toMatchObject({
+      userId: 'user-A',
+      principal: { kind: 'key', id: 'tok-1' },
+      kind: 'capability',
+      manual: null,
+      name: 'ask',
+      outcome: 'ok',
+    });
+    expect(typeof recorder.events[0].durationMs).toBe('number');
+    // The tool answered with an error result — recorded as such, not as ok.
+    expect(recorder.events[1]).toMatchObject({ kind: 'capability', name: 'boom', outcome: 'error' });
+  });
+
+  it('records a chain as a capability AND each call made inside it', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder });
+
+    await client.callTool({
+      name: 'call_tool_chain',
+      arguments: { code: "KNOWLEDGE_BASE.ask({ body: { prompt: 'one' } }); return KNOWLEDGE_BASE.ask({ body: { prompt: 'two' } });" },
+    });
+    await settle();
+
+    const names = recorder.events.map((e) => `${e.kind}:${e.name}:${e.outcome}`);
+    // The two inner calls finish (and are recorded) before the chain itself.
+    expect(names).toEqual(['capability:ask:ok', 'capability:ask:ok', 'capability:call_tool_chain:ok']);
+  });
+
+  it('attributes an OAuth caller to its agent connection, and records nothing for a caller with neither', async () => {
+    const asAgent = spyRecorder();
+    const agent = await setup({ auditRecorder: asAgent, tokenId: null, connectionId: 'conn-1' });
+    await agent.callTool({ name: 'ask', arguments: { body: { prompt: 'hi' } } });
+    await settle();
+    expect(asAgent.events[0]).toMatchObject({ principal: { kind: 'agent', id: 'conn-1' }, name: 'ask' });
+
+    const nobody = spyRecorder();
+    const jwt = await setup({ auditRecorder: nobody, tokenId: null, connectionId: null });
+    await jwt.callTool({ name: 'ask', arguments: { body: { prompt: 'hi' } } });
+    await settle();
+    expect(nobody.events).toEqual([]);
+  });
+
+  it('records a read inside a skill folder as that skill, and a read elsewhere as the read', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder, extraTools: ['read_file', 'list_skills'] });
+
+    await client.callTool({ name: 'read_file', arguments: { body: { path: 'Plugins/Sales/rfi/SKILL.md' } } });
+    await client.callTool({ name: 'read_file', arguments: { body: { path: 'KnowledgeBase/Product/roadmap.md' } } });
+    await settle();
+
+    expect(recorder.events[0]).toMatchObject({ kind: 'skill', manual: 'Plugins/Sales/rfi', name: 'rfi', outcome: 'ok' });
+    expect(recorder.events[1]).toMatchObject({ kind: 'capability', manual: null, name: 'read_file', outcome: 'ok' });
+  });
+
+  it('records a prompt read as a skill, with an error outcome when the skill is unknown', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder });
+    // The harness serves no get_skill endpoint, so every prompt is unknown here.
+    await expect(client.getPrompt({ name: 'rfi' })).rejects.toThrow(/Unknown skill/);
+    await settle();
+    expect(recorder.events[0]).toMatchObject({ kind: 'skill', name: 'rfi', outcome: 'error' });
+  });
+
+  it('records a call refused for a missing sign-in as denied, without running the tool', async () => {
+    const recorder = spyRecorder();
+    const vault = { statusFor: async (_u: string, keys: string[]) => keys.map((key) => ({ key, adminConfigured: false, userConfigured: false })) };
+    const manuals = {
+      userScopedKeysForManual: async (manual: string) =>
+        manual === 'KNOWLEDGE_BASE' ? [{ key: 'KNOWLEDGE_BASE_API_KEY', name: 'API_KEY', label: 'Your API key', oauth: false }] : [],
+    };
+    const client = await setup({ auditRecorder: recorder, secretsVault: vault, toolManuals: manuals });
+
+    const res = await client.callTool({ name: 'ask', arguments: { body: { prompt: 'hello' } } });
+    await settle();
+
+    expect(text(res)).not.toMatch(/echo:/);
+    expect(recorder.events).toEqual([
+      expect.objectContaining({ kind: 'capability', name: 'ask', outcome: 'denied', durationMs: null }),
+    ]);
+  });
+});

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

@@ -9,6 +9,7 @@ import type { InternalTokenService } from '../tool-auth/internal-token.service.j
 import { rejectConnectionKey } from '../tool-auth/connection-key-rejection.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../audit/audit.contract.js'; // Express Request augmentation (req.agentConnectionId)
 
 /**
  * Auth middleware for the MCP endpoint. Accepts any of:
@@ -111,6 +112,12 @@ export function createMcpAuthMiddleware(
         const info = await oauthProvider.verifyAccessToken(token);
         req.userId = String(info.extra?.userId ?? '');
         req.userEmail = String(info.extra?.userEmail ?? '');
+        // The agent behind the grant, for the Audit log. A token minted
+        // before connections existed carries none; the call then runs
+        // unattributed rather than refused.
+        if (typeof info.extra?.connectionId === 'string') {
+          req.agentConnectionId = info.extra.connectionId;
+        }
         if (!req.userId) {
           unauthorized(res, 'Invalid access token');
           return;
@@ -176,6 +183,30 @@ export function createMcpAuthMiddleware(
       }
       req.userId = user.id;
       req.userEmail = user.email;
+      // The local server's exchanged grant names its agent connection (see
+      // InternalTokenClaim.connectionId). The token itself is stateless and
+      // lives up to five hours, so the connection is asked on every request
+      // whether it still admits the agent — revoking the agent must reach
+      // this path as surely as it reaches the grant's own tokens. The use is
+      // stamped too (throttled, off the request's path), so the Audit log's
+      // "last used" follows the local server's calls, not only its sign-ins.
+      // Carried on the request so those calls are logged under the agent.
+      if (claim.connectionId) {
+        let live: boolean;
+        try {
+          live = await oauthProvider.isConnectionLive(claim.connectionId);
+        } catch (err) {
+          log.error('agent-connection check failed:', { err });
+          res.status(500).json({ error: 'Authentication backend unavailable' });
+          return;
+        }
+        if (!live) {
+          unauthorized(res, 'Access for this agent was revoked');
+          return;
+        }
+        oauthProvider.noteConnectionUse(claim.connectionId);
+        req.agentConnectionId = claim.connectionId;
+      }
       next();
       return;
     }

package/src/modules/mcp/mcp.routes.ts

@@ -115,6 +115,10 @@ export function createMcpRoutes(
           // undefined for OAuth/JWT) — resolved per request, so per-key metering
           // never depends on anything remembered from an earlier request.
           tokenId: req.externalApiKeyId ?? null,
+          // Agent-connection id (set for OAuth bearers and the local server's
+          // exchanged grant; undefined for keys/JWTs) — the Audit log's other
+          // principal, resolved per request like the key id.
+          connectionId: req.agentConnectionId ?? null,
           // The proxy authenticates its loopback calls with the SAME bearer the
           // client used here, so it acts on the request exactly as the caller would.
           bearer: extractBearer(req),
@@ -355,7 +359,13 @@ export function createMcpRoutes(
         grantRemainingMs === undefined
           ? MCP_LOOPBACK_TOKEN_TTL_MS
           : Math.min(MCP_LOOPBACK_TOKEN_TTL_MS, grantRemainingMs);
-      const minted = internalTokens.mint({ userId, externalProxy: true }, ttlMs);
+      // The grant's agent connection rides along, so the local server's
+      // calls with this token stay attributed to the agent in the Audit log.
+      const connectionId = typeof info.extra?.connectionId === 'string' ? info.extra.connectionId : undefined;
+      const minted = internalTokens.mint(
+        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}) },
+        ttlMs,
+      );
       // The ACTUAL lifetime, not the constant — the caller schedules its
       // proactive renewal off this number.
       res.json({ token: minted, expiresInMs: ttlMs });

package/src/modules/mcp/mcp.service.ts

@@ -54,6 +54,8 @@ import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.j
 import type { SpillStore } from '../workspace/spill-store.js';
 import { seedBevelHostedManualVars } from '../../shared/utcp-namespace.js';
 import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import type { IAgentEventRecorder } from '../audit/audit.contract.js';
+import { RequestAudit } from '../audit/request-audit.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
 import { DownstreamPool, POOL_KEY_SEPARATOR, type DownstreamPoolOptions, type Lease } from './downstream-pool.js';
 import { SurfaceLogThrottle } from './surface-log-throttle.js';
@@ -98,6 +100,12 @@ export interface McpCaller {
   userId: string;
   /** The connection-key id (per-key metering rides on it), or null for an OAuth/JWT bearer. */
   tokenId: string | null;
+  /**
+   * The agent connection behind an OAuth bearer (or the local server's
+   * exchanged grant), or null. With `tokenId`, the two ways a call is
+   * attributed in the Audit log; a request with neither records nothing.
+   */
+  connectionId?: string | null;
   /** The raw bearer the request carried. */
   bearer: string;
 }
@@ -268,6 +276,10 @@ export class McpService {
     // authorization when one of its TOOL sign-ins breaks. Optional: without
     // it, broken sign-ins surface only as the /connect link in the result.
     private readonly revokeOAuthAccess?: (bearer: string) => Promise<void>,
+    // The Audit log's recorder: every tool call, skill read and meta-tool run
+    // of a request that arrived with a key or an agent connection goes
+    // through it. Optional like the others; without it nothing is recorded.
+    private readonly auditRecorder?: IAgentEventRecorder,
   ) {
     this.downstream = new DownstreamPool<PooledDownstream>({
       ...opts.downstreamPool,
@@ -332,6 +344,7 @@ export class McpService {
    */
   async createRequestServer(caller: McpCaller, messages: unknown): Promise<Server> {
     const { userId, tokenId, bearer } = caller;
+    const connectionId = caller.connectionId ?? null;
     // The loopback surface (`/api/agent/*`) accepts connection keys and
     // internal tokens only. A connection-key request passes the caller's own
     // key through (per-key metering rides on it); an OAuth/JWT request's
@@ -347,8 +360,30 @@ export class McpService {
 
     let instructions: Promise<ComposedAgentInstructions> | undefined;
     const agentInstructions = () => (instructions ??= this.composeAgentInstructions());
+    // The Audit log's view of this request — only when the request can be
+    // attributed to a key or an agent connection. The catalog names it
+    // classifies pooled tools by are the surface's, which is built lazily
+    // below, so it reads them through a holder the surface fills in.
+    const catalogNamesHolder: { current: ReadonlyMap<string, string> } = { current: new Map() };
+    const principal = tokenId != null ? { kind: 'key' as const, id: tokenId } : connectionId ? { kind: 'agent' as const, id: connectionId } : null;
+    const audit =
+      this.auditRecorder && principal
+        ? new RequestAudit(this.auditRecorder, userId, principal, {
+            kbManualName: EXTERNAL_KB_MANUAL_NAME,
+            catalogNames: () => catalogNamesHolder.current,
+            loadSkills: () =>
+              this.fetchSkillList(loopbackBearer).then((skills) =>
+                skills.flatMap((s) => (s.path ? [{ name: s.name, path: s.path }] : [])),
+              ),
+          })
+        : null;
     let surface: Promise<RequestSurface> | undefined;
-    const requestSurface = () => (surface ??= this.buildSurface(userId, tokenId, loopbackBearer));
+    const requestSurface = () =>
+      (surface ??= this.buildSurface(userId, tokenId, loopbackBearer).then((built) => {
+        catalogNamesHolder.current = built.catalogNames;
+        audit?.instrumentChainCalls(built.client);
+        return built;
+      }));
 
     const initializing = (Array.isArray(messages) ? messages : [messages]).some((m) => isInitializeRequest(m));
     const server = new Server(
@@ -432,8 +467,12 @@ export class McpService {
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
       const { client, tools, unavailable, catalogNames } = await requestSurface();
       const toolName = request.params.name;
+      const args = request.params.arguments ?? {};
       if (META_TOOL_NAMES.has(toolName)) {
-        return this.dispatchMetaTool(client, toolName, request.params.arguments ?? {});
+        // A meta-tool is the platform's own; its inner tool calls (a chain's)
+        // are recorded one by one through the instrumented client.
+        const run = () => this.dispatchMetaTool(client, toolName, args);
+        return audit ? audit.call(toolName, args, run, isErrorResult) : run();
       }
       /**
        * The needs-authorization answer, when the caller's sign-in for the
@@ -476,11 +515,18 @@ export class McpService {
           .filter((m) => toolName.startsWith(`${m.utcpName}_`))
           .sort((a, b) => b.utcpName.length - a.utcpName.length)[0];
         const answer = owner ? await needsAuthorization(owner.utcpName) : null;
+        if (answer && owner && audit) {
+          await audit.denied(`${owner.utcpName}.${toolName.slice(owner.utcpName.length + 1)}`, args);
+        }
         return answer ?? toolError(retiredToolMessage(toolName) ?? `Unknown tool "${toolName}".`);
       }
       const needsAuth = await needsAuthorization(proxied.manualName);
-      if (needsAuth) return needsAuth;
-      return this.dispatch(client, proxied, request, extra);
+      if (needsAuth) {
+        if (audit) await audit.denied(proxied.utcpName, args);
+        return needsAuth;
+      }
+      const run = () => this.dispatch(client, proxied, request, extra);
+      return audit ? audit.call(proxied.utcpName, args, run, isErrorResult) : run();
     });
 
     // Prompts = skills. Each skill becomes a user-callable prompt (slash command
@@ -499,7 +545,14 @@ export class McpService {
     });
 
     server.setRequestHandler(GetPromptRequestSchema, async (request): Promise<GetPromptResult> => {
+      const started = performance.now();
       const skill = await this.fetchSkill(loopbackBearer, request.params.name);
+      // A prompt IS a skill read — the same event `get_skill` produces.
+      audit?.emit(
+        { kind: 'skill', manual: skill?.path ?? null, name: request.params.name },
+        skill ? 'ok' : 'error',
+        Math.round(performance.now() - started),
+      );
       if (!skill) {
         throw new McpError(ErrorCode.InvalidParams, `Unknown skill "${request.params.name}".`);
       }
@@ -1176,6 +1229,11 @@ export class McpService {
   }
 }
 
+/** Whether a tool result is the tool saying it failed — what the Audit log records as `error`. */
+function isErrorResult(result: CallToolResult): boolean {
+  return result.isError === true;
+}
+
 /**
  * The UTCP client config for `userId`: the given variables, plus the per-user
  * `bevel-secrets` loader that resolves every `${SECRET}` ref lazily. Shared by