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

package/src/modules/audit/__tests__/event-classifier.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import { classifyToolCall, skillContaining, skillReadPath, splitUtcpName } from '../event-classifier.js';
+
+const KB = 'KNOWLEDGE_BASE';
+const ctx = { kbManualName: KB, catalogNames: new Map([['my_server', 'my-server']]) };
+const skills = [
+  { name: 'rfi', path: 'Plugins/Sales/rfi' },
+  { name: 'deploy-checklist', path: 'Skills/Engineering/deploy-checklist' },
+  // Nested under another skill's folder: the longer match must win.
+  { name: 'rfi-followup', path: 'Plugins/Sales/rfi/followup' },
+];
+
+describe('splitUtcpName', () => {
+  it('splits on the first dot and leaves a bare name without a manual', () => {
+    expect(splitUtcpName('KNOWLEDGE_BASE.read_file')).toEqual({ manual: 'KNOWLEDGE_BASE', tool: 'read_file' });
+    expect(splitUtcpName('notion.notion-search')).toEqual({ manual: 'notion', tool: 'notion-search' });
+    expect(splitUtcpName('call_tool_chain')).toEqual({ manual: '', tool: 'call_tool_chain' });
+  });
+});
+
+describe('skillReadPath', () => {
+  it('asks for the skill catalog only for a platform read that names a path, or a get_skill with a name', () => {
+    expect(skillReadPath(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, KB)).toBe(
+      'Plugins/Sales/rfi/SKILL.md',
+    );
+    expect(skillReadPath(`${KB}.grep`, { path: 'Skills' }, KB)).toBe('Skills');
+    expect(skillReadPath(`${KB}.get_skill`, { body: { name: 'rfi' } }, KB)).toBe('');
+    // Not worth a catalog fetch: a write, a read with no path, another manual's tool, a meta-tool.
+    expect(skillReadPath(`${KB}.write_file`, { body: { path: 'Plugins/x' } }, KB)).toBeNull();
+    expect(skillReadPath(`${KB}.read_file`, { body: {} }, KB)).toBeNull();
+    expect(skillReadPath('notion.search', { body: { path: 'Plugins/x' } }, KB)).toBeNull();
+    expect(skillReadPath('call_tool_chain', { code: 'x' }, KB)).toBeNull();
+  });
+});
+
+describe('skillContaining', () => {
+  it('matches a path inside a skill folder on a segment boundary, from either root, longest folder first', () => {
+    expect(skillContaining('Plugins/Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('knowledge-base/Plugins/Sales/rfi/scripts/build.py', skills)?.name).toBe('rfi');
+    expect(skillContaining('./Skills\\Engineering\\deploy-checklist\\SKILL.md', skills)?.name).toBe('deploy-checklist');
+    expect(skillContaining('Plugins/Sales/rfi/followup/SKILL.md', skills)?.name).toBe('rfi-followup');
+    // The file tools accept a doubled separator as the same path; so does this.
+    expect(skillContaining('Plugins//Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
+    // `.` and `..` are resolved before matching: a path that climbs out of a
+    // skill folder is not a read of that skill, and one that climbs above its
+    // own start is no place at all.
+    expect(skillContaining('Plugins/Sales/rfi/./SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('Plugins/Sales/other/../rfi/SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('Plugins/Sales/rfi/../../../KnowledgeBase/Secrets.md', skills)).toBeNull();
+    expect(skillContaining('../Plugins/Sales/rfi/SKILL.md', skills)).toBeNull();
+    // A folder that merely shares a prefix is not the skill's folder.
+    expect(skillContaining('Plugins/Sales/rfi-old/notes.md', skills)).toBeNull();
+    expect(skillContaining('KnowledgeBase/Product/roadmap.md', skills)).toBeNull();
+  });
+});
+
+describe('classifyToolCall', () => {
+  it('logs the platform manual and the meta-tools as hexis capabilities, by bare name', () => {
+    expect(classifyToolCall(`${KB}.write_file`, { body: { path: 'x' } }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'write_file',
+    });
+    expect(classifyToolCall('call_tool_chain', { code: 'x' }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'call_tool_chain',
+    });
+  });
+
+  it("logs another manual's tool as a tool under its catalog name", () => {
+    expect(classifyToolCall('my_server.search', { q: 'x' }, ctx, null)).toEqual({
+      kind: 'tool',
+      manual: 'my-server',
+      name: 'search',
+    });
+    // An http `.tool` manual has no rewrite, so its registered name is the catalog name.
+    expect(classifyToolCall('hubspot.search_contacts', {}, ctx, null)).toEqual({
+      kind: 'tool',
+      manual: 'hubspot',
+      name: 'search_contacts',
+    });
+  });
+
+  it('logs get_skill as a skill read, with the folder when the catalog knows it', () => {
+    expect(classifyToolCall(`${KB}.get_skill`, { body: { name: 'rfi' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+    });
+    expect(classifyToolCall(`${KB}.get_skill`, { name: 'unknown' }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: null,
+      name: 'unknown',
+    });
+  });
+
+  it('logs a platform read inside a skill folder as that skill, and elsewhere as the read', () => {
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+    });
+    expect(classifyToolCall(`${KB}.list_files`, { body: { path: 'Skills/Engineering/deploy-checklist' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Skills/Engineering/deploy-checklist',
+      name: 'deploy-checklist',
+    });
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'KnowledgeBase/Product/roadmap.md' } }, ctx, skills)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+    });
+    // No catalog (the fetch failed): the honest fallback is the read itself.
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+    });
+  });
+});

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

@@ -0,0 +1,316 @@
+import { and, asc, count, desc, eq, 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 type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import {
+  AuditPrincipalNotFoundError,
+  InvalidCursorError,
+  isUuid,
+  parseRetentionWindow,
+  type AgentEventInput,
+  type AgentEventPage,
+  type AgentEventView,
+  type AuditPrincipal,
+  type AuditPrincipalRef,
+  type AuditScope,
+  type IAgentAuditService,
+  type IAgentEventRecorder,
+} from './audit.contract.js';
+
+const log = logger('audit');
+
+/** The most events one page may carry; the routes clamp to it. */
+export const MAX_EVENT_PAGE = 200;
+
+/** How often, at most, one process sweeps events past the retention window. */
+const PRUNE_INTERVAL_MS = 60 * 60_000;
+
+/**
+ * The Audit log: the write half the MCP proxy records through, and the read
+ * and revoke half its page is built on.
+ *
+ * Writes are fire-and-forget by contract — a tool result must never wait on,
+ * or fail over, its own bookkeeping. Retention is enforced opportunistically
+ * on the write path (one sweep per process per hour, piggybacked on an
+ * insert), the same way the OAuth tables prune themselves on mint: no
+ * scheduler, and a deployment that records nothing has nothing to sweep.
+ *
+ * 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 {
+  private lastPruneAt = 0;
+
+  constructor(
+    private readonly db: Database,
+    private readonly keys: Pick<IExternalApiKeyService, 'listForUser' | 'listForDeployment' | 'ownerOf'>,
+    /** Read per sweep, so a changed setting applies without a restart; null = keep forever. */
+    private readonly retentionDays: () => number | null,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  record(event: AgentEventInput): void {
+    this.db
+      .insert(agentEvents)
+      .values({
+        userId: event.userId,
+        keyId: event.principal.kind === 'key' ? event.principal.id : null,
+        connectionId: event.principal.kind === 'agent' ? event.principal.id : null,
+        kind: event.kind,
+        manual: event.manual,
+        name: event.name,
+        outcome: event.outcome,
+        durationMs: event.durationMs,
+        at: new Date(this.now()),
+      })
+      .then(
+        () => this.maybePrune(),
+        (err) => log.warn('recording an agent event failed:', { err }),
+      );
+  }
+
+  /**
+   * Sweep events older than the retention window — at most once per hour per
+   * process, best-effort, never awaited by a caller. A deployment that keeps
+   * events forever sweeps nothing.
+   */
+  private async maybePrune(): Promise<void> {
+    const now = this.now();
+    if (now - this.lastPruneAt < PRUNE_INTERVAL_MS) return;
+    this.lastPruneAt = now;
+    const days = this.retentionDays();
+    if (days === null) return;
+    const cutoff = new Date(now - days * 24 * 60 * 60_000);
+    try {
+      await this.db.delete(agentEvents).where(lt(agentEvents.at, cutoff));
+    } catch (err) {
+      log.warn('agent-event prune failed (non-fatal):', { err });
+    }
+  }
+
+  async listPrincipals(scope: AuditScope): Promise<AuditPrincipal[]> {
+    const mine = scope === 'all' ? null : scope.userId;
+    const [keyRows, connectionRows, countRows] = await Promise.all([
+      mine === null ? this.keys.listForDeployment() : this.keysForUser(mine),
+      this.db
+        .select({
+          connection: agentConnections,
+          user: { id: users.id, email: users.email, name: users.name },
+        })
+        .from(agentConnections)
+        .innerJoin(users, eq(agentConnections.userId, users.id))
+        .where(mine === null ? undefined : eq(agentConnections.userId, mine))
+        .orderBy(asc(users.email), desc(agentConnections.connectedAt)),
+      this.db
+        .select({ keyId: agentEvents.keyId, connectionId: agentEvents.connectionId, n: count() })
+        .from(agentEvents)
+        .where(mine === null ? undefined : eq(agentEvents.userId, mine))
+        .groupBy(agentEvents.keyId, agentEvents.connectionId),
+    ]);
+
+    const counts = new Map<string, number>();
+    for (const row of countRows) {
+      const id = row.keyId ?? row.connectionId;
+      if (id) counts.set(id, Number(row.n));
+    }
+
+    const principals: AuditPrincipal[] = [
+      ...keyRows.map((k) => ({
+        kind: 'key' as const,
+        id: k.id,
+        label: k.label,
+        keyKind: k.kind,
+        createdAt: k.createdAt,
+        lastUsedAt: k.lastUsedAt,
+        revokedAt: k.revokedAt,
+        revokedBy: k.revokedBy,
+        deletedAt: k.deletedAt,
+        eventCount: counts.get(k.id) ?? 0,
+        user: k.user,
+      })),
+      ...connectionRows.map(({ connection: c, user }) => ({
+        kind: 'agent' as const,
+        id: c.id,
+        label: c.clientName ?? 'Unnamed agent',
+        createdAt: c.connectedAt.getTime(),
+        lastUsedAt: c.lastUsedAt ? c.lastUsedAt.getTime() : null,
+        revokedAt: c.revokedAt ? c.revokedAt.getTime() : null,
+        revokedBy: (c.revokedBy as 'owner' | 'admin' | null) ?? null,
+        eventCount: counts.get(c.id) ?? 0,
+        user,
+      })),
+    ];
+    // Per account (by email), live before revoked, most recently used first,
+    // newest first among the never-used — the order the page shows without
+    // re-sorting, and the one the Connection keys overview had.
+    principals.sort((a, b) => {
+      const byEmail = a.user.email.localeCompare(b.user.email);
+      if (byEmail !== 0) return byEmail;
+      const aRevoked = a.revokedAt !== null;
+      const bRevoked = b.revokedAt !== null;
+      if (aRevoked !== bRevoked) return aRevoked ? 1 : -1;
+      const byUse = (b.lastUsedAt ?? 0) - (a.lastUsedAt ?? 0);
+      return byUse !== 0 ? byUse : b.createdAt - a.createdAt;
+    });
+    return principals;
+  }
+
+  /** One person's keys, with the owner attached the way the deployment listing attaches it. */
+  private async keysForUser(userId: string) {
+    const [keys, [user]] = await Promise.all([
+      this.keys.listForUser(userId),
+      this.db
+        .select({ id: users.id, email: users.email, name: users.name })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1),
+    ]);
+    if (!user) return [];
+    return keys.map((k) => ({ ...k, user }));
+  }
+
+  async ownerOf(principal: AuditPrincipalRef): Promise<string | null> {
+    if (principal.kind === 'agent') {
+      const [row] = await this.db
+        .select({ userId: agentConnections.userId })
+        .from(agentConnections)
+        .where(eq(agentConnections.id, principal.id))
+        .limit(1);
+      return row?.userId ?? null;
+    }
+    // A key is the key service's to answer for, like every other read of one.
+    return this.keys.ownerOf(principal.id);
+  }
+
+  async listEvents(
+    principal: AuditPrincipalRef,
+    page: { before?: string; limit: number },
+  ): Promise<AgentEventPage> {
+    const limit = Math.max(1, Math.min(MAX_EVENT_PAGE, Math.floor(page.limit)));
+    const byPrincipal =
+      principal.kind === 'key'
+        ? eq(agentEvents.keyId, principal.id)
+        : eq(agentEvents.connectionId, principal.id);
+    // Keyset on (at, id): a page boundary between two events at the same
+    // instant is still a boundary, and a row inserted while the reader pages
+    // never shifts what the next page returns.
+    const cursor = page.before ? parseCursor(page.before) : null;
+    if (page.before && !cursor) throw new InvalidCursorError();
+    const after: SQL | undefined = cursor
+      ? or(
+          lt(agentEvents.at, cursor.at),
+          and(eq(agentEvents.at, cursor.at), lt(agentEvents.id, cursor.id)),
+        )
+      : undefined;
+    // The total is counted on the FIRST page only: a reader paging back
+    // through a busy principal's history would otherwise pay a full count of
+    // the same number on every step, for a figure the page already holds.
+    const [rows, totals] = await Promise.all([
+      this.db
+        .select({
+          id: agentEvents.id,
+          kind: agentEvents.kind,
+          manual: agentEvents.manual,
+          name: agentEvents.name,
+          outcome: agentEvents.outcome,
+          at: agentEvents.at,
+        })
+        .from(agentEvents)
+        .where(and(byPrincipal, after))
+        .orderBy(desc(agentEvents.at), desc(agentEvents.id))
+        .limit(limit + 1),
+      cursor ? null : this.db.select({ total: count() }).from(agentEvents).where(byPrincipal),
+    ]);
+    const hasMore = rows.length > limit;
+    const pageRows = hasMore ? rows.slice(0, limit) : rows;
+    const events: AgentEventView[] = pageRows.map((r) => ({
+      id: r.id,
+      kind: r.kind as AgentEventView['kind'],
+      manual: r.manual,
+      name: r.name,
+      outcome: r.outcome as AgentEventView['outcome'],
+      at: r.at.getTime(),
+    }));
+    const last = pageRows[pageRows.length - 1];
+    return {
+      events,
+      total: totals ? Number(totals[0]?.total ?? 0) : null,
+      nextCursor: hasMore && last ? formatCursor(last.at, last.id) : null,
+    };
+  }
+
+  async revokeConnection(id: string, by: 'owner' | 'admin', ownerUserId?: string): Promise<void> {
+    const scope = ownerUserId
+      ? and(eq(agentConnections.id, id), eq(agentConnections.userId, ownerUserId))!
+      : eq(agentConnections.id, id);
+    await this.db.transaction(async (tx) => {
+      const revoked = await tx
+        .update(agentConnections)
+        .set({ revokedAt: new Date(this.now()), revokedBy: by })
+        .where(and(scope, isNull(agentConnections.revokedAt)))
+        .returning({ id: agentConnections.id });
+      if (revoked.length === 0) {
+        // Already revoked stays idempotent; out of scope or unknown throws —
+        // the same split `ExternalApiKeyService.markRevoked` makes.
+        const [existing] = await tx
+          .select({ id: agentConnections.id })
+          .from(agentConnections)
+          .where(scope)
+          .limit(1);
+        if (!existing) throw new AuditPrincipalNotFoundError();
+        return;
+      }
+      // Every live token of the connection, access and refresh alike: the
+      // agent's next request 401s, its refresh fails, and re-authorizing —
+      // through the browser, as a person — is the only way back in.
+      await tx
+        .update(oauthTokens)
+        .set({ revokedAt: new Date(this.now()) })
+        .where(and(eq(oauthTokens.connectionId, id), isNull(oauthTokens.revokedAt)));
+    });
+  }
+}
+
+/** `<epoch ms>.<uuid>` — the page's opaque-enough cursor. */
+function formatCursor(at: Date, id: string): string {
+  return `${at.getTime()}.${id}`;
+}
+
+/**
+ * The cursor back into its parts, or null for anything this service did not
+ * issue: the id must be a uuid (the column is one, and Postgres refuses to
+ * compare it with anything else) and the instant a whole number of epoch
+ * milliseconds a `timestamp` can hold.
+ */
+function parseCursor(raw: string): { at: Date; id: string } | null {
+  const dot = raw.indexOf('.');
+  if (dot < 0) return null;
+  const msText = raw.slice(0, dot);
+  const id = raw.slice(dot + 1);
+  if (!/^\d{1,15}$/.test(msText) || !isUuid(id)) return null;
+  return { at: new Date(Number(msText)), id };
+}
+
+/** The last invalid setting value warned about, so a standing misconfiguration is said once, not once per prune. */
+let warnedInvalidRetention: string | null = null;
+
+/**
+ * The retention window the service runs on, in days — or null to keep
+ * events forever, which is what a blank, zero or negative setting means. A
+ * value that is not a window at all is kept-forever too, said out loud once:
+ * the Deployment page shows an environment value as the one in effect and
+ * would otherwise be the only place claiming a window nobody is keeping.
+ */
+export function retentionDaysFrom(raw: string): number | null {
+  const window = parseRetentionWindow(raw);
+  if (window === 'forever') return null;
+  if (window !== null) return window.days;
+  if (raw !== warnedInvalidRetention) {
+    warnedInvalidRetention = raw;
+    log.warn(
+      `auditRetentionDays is "${raw}", which is not a whole number of days — keeping events forever until it is fixed.`,
+    );
+  }
+  return null;
+}

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

@@ -0,0 +1,83 @@
+import type { RequestHandler } from 'express';
+import { logger } from '../../shared/logging.js';
+import type { IAgentEventRecorder } from './audit.contract.js';
+import { classifyToolCall, skillReadPath, type SkillFolder } from './event-classifier.js';
+import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
+
+const log = logger('audit');
+
+export interface AgentRestAuditDeps {
+  recorder: IAgentEventRecorder;
+  /** The registered name of the platform's own manual (`KNOWLEDGE_BASE`). */
+  kbManualName: string;
+  /** The caller's skill catalog, for telling a skill read from a file read; fetched only when a read names a path. */
+  skillFolders: (userId: string) => Promise<readonly SkillFolder[]>;
+}
+
+/**
+ * Records the REST tool calls the LOCAL server makes directly — the ones that
+ * never pass through the hosted MCP endpoint, where every other call an agent
+ * makes is recorded.
+ *
+ * hexis-mcp reaches the deployment two ways. Tool calls go through the
+ * hosted `/api/mcp` as its remote manual, and the proxy records them there.
+ * But the skill catalog and a skill's body are read straight off the REST
+ * surface (`list_skills`, `get_skill`, `list_local_tools`, …) with the
+ * internal token the server exchanged its grant for — so a person loading a
+ * skill as a slash command in Claude Code through the local server left no
+ * `skill` event, while the same read through the hosted endpoint did.
+ *
+ * WHICH calls are recorded here is decided by the credential, not the route:
+ * only an `externalProxy` token that names an agent connection — the
+ * exchanged grant — is recorded. The hosted proxy's own loopback tokens name
+ * none, so a call the proxy has already recorded is never counted twice;
+ * and a connection key reaching REST directly is indistinguishable from the
+ * proxy passing that same key through, so keys stay recorded at the proxy
+ * alone. The rule is the credential's shape, which no caller chooses.
+ *
+ * Mounted in front of every `/agent/tools/:name` route and judging on
+ * `finish`, when the route's own auth has run and the status is known: a 2xx
+ * is `ok`, anything else `error`. Never on the tool's critical path — the
+ * classification (and the skill catalog it may need) runs after the answer
+ * has gone out.
+ */
+export function createAgentRestAuditMiddleware(deps: AgentRestAuditDeps): RequestHandler {
+  return (req, res, next) => {
+    const started = performance.now();
+    // Read NOW: `req.params` is rewritten for each layer Express matches, and
+    // by `finish` it is the route's own (empty) set, not this mount's.
+    const name = String(req.params.name ?? '');
+    res.on('finish', () => {
+      const auth = req.toolAuth;
+      if (!auth || auth.source !== 'external' || !auth.connectionId) return;
+      if (!name) return;
+      const durationMs = Math.max(0, Math.round(performance.now() - started));
+      const outcome = res.statusCode < 400 ? 'ok' : 'error';
+      const args = (req.body && typeof req.body === 'object' ? req.body : {}) as Record<string, unknown>;
+      const utcpName = `${deps.kbManualName}.${name}`;
+      const ctx = { kbManualName: deps.kbManualName, catalogNames: new Map<string, string>() };
+      const record = (skills: readonly SkillFolder[] | null) => {
+        try {
+          deps.recorder.record({
+            userId: auth.userId,
+            principal: { kind: 'agent', id: auth.connectionId! },
+            ...classifyToolCall(utcpName, args, ctx, skills),
+            outcome,
+            durationMs,
+          });
+        } catch (err) {
+          log.warn('recording a REST agent event failed:', { err });
+        }
+      };
+      if (skillReadPath(utcpName, args, deps.kbManualName) === null) {
+        record(null);
+        return;
+      }
+      deps.skillFolders(auth.userId).then(record, (err) => {
+        log.warn('skill catalog unavailable for audit classification:', { err });
+        record(null);
+      });
+    });
+    next();
+  };
+}

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

@@ -0,0 +1,164 @@
+/**
+ * The Audit log's contracts: what an external agent's activity is recorded
+ * as, who a recorded call is attributed to, and the two services around
+ * them — the recorder the MCP proxy writes through, and the read/revoke
+ * service the Audit log page is built on.
+ */
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      /**
+       * The agent connection (`agent_connections.id`) an OAuth-authenticated
+       * MCP request arrived through — bound by the MCP auth middleware from
+       * the access token, or from the `connectionId` claim of the internal
+       * token the local server exchanged its grant for. Unset for connection
+       * keys (those carry `externalApiKeyId`) and for browser sessions.
+       */
+      agentConnectionId?: string;
+    }
+  }
+}
+
+/** What was called: the platform's own tool, a manual's tool, or a skill read. */
+export type AgentEventKind = 'capability' | 'tool' | 'skill';
+
+/** How the call ended. `denied`: the caller's sign-in for the tool was missing, so nothing ran. */
+export type AgentEventOutcome = 'ok' | 'error' | 'denied';
+
+/**
+ * Who a call is attributed to: the connection key it was authenticated with,
+ * or the agent connection behind its OAuth grant. Exactly one.
+ */
+export type AuditPrincipalRef = { kind: 'key'; id: string } | { kind: 'agent'; id: string };
+
+/** One recorded call, as the recorder takes it. */
+export interface AgentEventInput {
+  userId: string;
+  principal: AuditPrincipalRef;
+  kind: AgentEventKind;
+  /** The MCP server / `.tool` manual for a tool, the skill folder for a skill; null for a capability. */
+  manual: string | null;
+  name: string;
+  outcome: AgentEventOutcome;
+  durationMs: number | null;
+}
+
+/**
+ * The write half. `record` never throws and never blocks the call it
+ * describes: a recording failure is logged and the tool result still goes
+ * back to the agent.
+ */
+export interface IAgentEventRecorder {
+  record(event: AgentEventInput): void;
+}
+
+/** One row of the Audit log: an agent connection or a connection key, with its owner. */
+export interface AuditPrincipal {
+  kind: 'key' | 'agent';
+  id: string;
+  /** The key's label, or the agent's registered client name. */
+  label: string;
+  /**
+   * For a key: what it was minted as (`key` by hand, `github-link` for a
+   * Claude link). Absent for an agent.
+   */
+  keyKind?: string;
+  /** When the key was created / the agent connected. Epoch ms. */
+  createdAt: number;
+  lastUsedAt: number | null;
+  revokedAt: number | null;
+  /** Who ended it, once revoked: the owner, or an admin. */
+  revokedBy: 'owner' | 'admin' | null;
+  /** For a key: when its owner deleted it for good. Such rows reach admins only. */
+  deletedAt?: number | null;
+  /** Events currently on record for it (within the retention window). */
+  eventCount: number;
+  user: { id: string; email: string; name: string };
+}
+
+/** One event as the page reads it. */
+export interface AgentEventView {
+  id: string;
+  kind: AgentEventKind;
+  manual: string | null;
+  name: string;
+  outcome: AgentEventOutcome;
+  at: number;
+}
+
+export interface AgentEventPage {
+  events: AgentEventView[];
+  /**
+   * Every event on record for the principal, not just this page — counted
+   * on the first page only; null on a page reached through a cursor, since
+   * the reader already holds the figure.
+   */
+  total: number | null;
+  /** Pass back as `before` to load the next (older) page; null when this was the last. */
+  nextCursor: string | null;
+}
+
+/** Whose rows: one person's, or the whole deployment's (admins). */
+export type AuditScope = { userId: string } | 'all';
+
+export interface IAgentAuditService {
+  listPrincipals(scope: AuditScope): Promise<AuditPrincipal[]>;
+  /** The account a principal belongs to, or null when there is no such principal. The routes' ownership check. */
+  ownerOf(principal: AuditPrincipalRef): Promise<string | null>;
+  listEvents(
+    principal: AuditPrincipalRef,
+    page: { before?: string; limit: number },
+  ): Promise<AgentEventPage>;
+  /**
+   * Cut an agent off: mark its connection revoked and revoke every live
+   * token it holds, so its next request fails and its refresh fails with it.
+   * `ownerUserId` scopes the revoke to the person's own connections; an admin
+   * passes none. Idempotent on an already-revoked connection; throws
+   * {@link AuditPrincipalNotFoundError} when nothing matches.
+   */
+  revokeConnection(id: string, by: 'owner' | 'admin', ownerUserId?: string): Promise<void>;
+}
+
+export class AuditPrincipalNotFoundError extends Error {
+  constructor() {
+    super('No such agent or key');
+    this.name = 'AuditPrincipalNotFoundError';
+  }
+}
+
+/** A `before` cursor that is not one this service issued — the caller's mistake, answered as such. */
+export class InvalidCursorError extends Error {
+  constructor() {
+    super('Invalid cursor');
+    this.name = 'InvalidCursorError';
+  }
+}
+
+/** Shape of the id columns (any uuid version; case-insensitive). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isUuid(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+/**
+ * The retention window's one rule, shared by the setting's validator and the
+ * runtime reader. A positive whole number of days is the window; blank,
+ * zero or a negative number is "keep forever" — the deployment's choice,
+ * made the same way whether typed on the Deployment page or set through
+ * `AUDIT_RETENTION_DAYS`. Anything else is not a window at all: the
+ * validator refuses the save, and the reader, which cannot refuse, keeps
+ * everything and says so.
+ */
+export type RetentionWindow = { days: number } | 'forever';
+
+/** The window a retention setting names, or null when it names none this rule accepts. */
+export function parseRetentionWindow(raw: string): RetentionWindow | null {
+  const trimmed = raw.trim();
+  if (trimmed === '') return 'forever';
+  if (!/^-?\d+$/.test(trimmed)) return null;
+  const n = Number(trimmed);
+  return n > 0 ? { days: n } : 'forever';
+}