@bevel-software/platform-core-backend 0.30.0 → 0.32.0

package/migrations/meta/_journal.json

@@ -127,6 +127,20 @@
       "when": 1791359019161,
       "tag": "0017_atlassian_account_links",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1792106401545,
+      "tag": "0018_agent_events_page",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1792404850653,
+      "tag": "0019_oauth_token_rotated_at",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.30.0",
+  "version": "0.32.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",
@@ -55,8 +55,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.30.0",
-    "@bevel-software/platform-shared": "0.30.0"
+    "@bevel-software/platform-mcp-core": "0.32.0",
+    "@bevel-software/platform-shared": "0.32.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/catalog-revision.ts

@@ -12,9 +12,9 @@ const log = logger('catalog-revision');
  * skill the default branch serves them, right now.
  *
  * It exists for a client that holds a long-lived connection and cannot be told
- * anything: the local `hexis-mcp` server. The hosted endpoint is stateless, so
- * every request there already rebuilds its surface from the live registry
- * (`mcp.routes.stateless.test.ts` pins that). A process on someone's laptop
+ * anything: the local `hexis-mcp` server. The hosted endpoint reads it too, on
+ * every request, to pick the caller's cached tool client: a new revision is a
+ * new build (`mcp.surface-cache.test.ts` pins that). A process on someone's laptop
  * registered the deployment's manual ONCE, at startup, and would otherwise
  * serve that startup's toolset until it is restarted. Polling this tells it —
  * cheaply, and without a second way for the catalogs to be read — exactly when

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

@@ -470,7 +470,8 @@ export async function createCoreServer(
   // `get_skill`. Warnings only; it never refuses a save.
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
   // `delete_branch` sees change requests as `get_change_request` does.
-  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee);
+  // The history tools take the per-file read the file itself takes (`accessControl`).
+  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee, core.accessControl, agentAccessGate);
   // The five read tools over change requests. Separate from the workflow tools
   // because they are the only ones that gate their whole payload on the
   // caller's read access, so they take the access service and nothing else.

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

@@ -117,7 +117,7 @@ import { ConnectionProbeService } from '../modules/connection-probe/index.js';
 import { GitService } from '../modules/workflow/git/git.service.js';
 import { NodeGitRunner } from '../modules/workflow/git/node-git-runner.js';
 import { PullRequestService } from '../modules/workflow/git/pull-request.service.js';
-import { WorkspaceMutex } from '../modules/kb-fs/mutex.js';
+import { WorkspaceIdMutex, WorkspaceMutex } from '../modules/kb-fs/mutex.js';
 import { assertGitVersion } from '../modules/workflow/git/git-version.js';
 import { DiffService } from '../modules/diff/diff.service.js';
 import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
@@ -127,6 +127,7 @@ import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { StarterPackService } from '../modules/onboarding/starter-pack.service.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
+import { ChangeRequestHooks, type IChangeRequestHooks } from '../modules/workflow/change-request-hooks.js';
 import { PendingCommitsService } from '../modules/workflow/pending-commits.service.js';
 import {
   PendingCommitsWorker,
@@ -324,6 +325,12 @@ export interface CoreServices {
   reviewWorkflowService: ReviewWorkflowService;
   fileLockService: FileLockService;
   workflowService: WorkflowService;
+  /**
+   * The seam for "a change request was opened": a deployment registers here
+   * how the reviewers are told (the cloud's mail, say), and the open's answer
+   * says whether somebody did. Core registers nothing.
+   */
+  changeRequestHooks: IChangeRequestHooks;
   /** Remote sync (`POST /api/sync`): a git host or pipeline makes the clones catch up. */
   kbSyncService: KbSyncService;
   eventBus: WorkflowEventBus;
@@ -578,7 +585,9 @@ export async function createCoreServices(
    */
   // Shared mutex so git and diff operations on the same workspace serialize
   // against each other — a backup-reseed races a concurrent commit otherwise.
-  const workspaceMutex = new WorkspaceMutex();
+  // Keyed by the CANONICAL workspace id: a route's Express-decoded `:id` and
+  // a tool's encoded one reserve the same clone (see `WorkspaceIdMutex`).
+  const workspaceMutex = new WorkspaceIdMutex();
   /**
    * The knowledge base's ONE repository: every branch workspace is a worktree
    * of it (see `kb-repository.ts`). One instance, handed to the workspace
@@ -948,6 +957,10 @@ export async function createCoreServices(
   // id-repair keeps the id namespace collision-free. Subscribers are registered
   // below, once the reacting services exist.
   const fileChangeNotifier = new FileChangeNotifier();
+  // Who tells the reviewers of an opened change request: the composition root
+  // of a distribution registers its listener here, after this returns (see
+  // `ChangeRequestHooks`).
+  const changeRequestHooks = new ChangeRequestHooks();
   const workflowService = new WorkflowService(
     db,
     gitService,
@@ -965,6 +978,11 @@ export async function createCoreServices(
     // the agent-access gate consult, so a deployment's registrations against
     // it reach every hook point.
     workflowHooks,
+    // Exposed as `changeRequestHooks`, the same instance, for the same reason.
+    changeRequestHooks,
+    // The opened event names the approvers as accounts; auth answers which
+    // of the addresses the access model names have one.
+    authService,
   );
   // The leftover-branch cleanup asks the Deployment page at every round, so
   // switching it off there applies without a restart.
@@ -1666,6 +1684,7 @@ export async function createCoreServices(
     reviewWorkflowService,
     fileLockService,
     workflowService,
+    changeRequestHooks,
     kbSyncService,
     eventBus,
     fileChangeNotifier,

package/src/index.ts

@@ -151,3 +151,10 @@ export {
   type AgentReadHook,
   type PreWriteHook,
 } from './modules/workflow/workflow-hooks.js';
+export {
+  ChangeRequestHooks,
+  type ChangeRequestOpenedEvent,
+  type ChangeRequestOpenedHook,
+  type ChangeRequestPerson,
+  type IChangeRequestHooks,
+} from './modules/workflow/change-request-hooks.js';

package/src/modules/access/access-control.service.ts

@@ -5,7 +5,7 @@ import { logger } from '../../shared/logging.js';
 const log = logger('access');
 
 import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.contract.js';
-import { assertOneSpecPerLine, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
+import { assertOneSpecPerLine, isCommitSha, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
 import { hashEmail } from '../../shared/email-identity.js';
 import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
 import { readRevSha } from '../kb-fs/index.js';
@@ -67,11 +67,6 @@ import {
   DIRECTORY_SYNC_BOT_NAME,
 } from './directory-sync-bot.js';
 
-/** A full object id, which is what every at-ref gate resolves its ref to before reading. */
-function isCommitSha(ref: string): boolean {
-  return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(ref);
-}
-
 /**
  * What one spec of a batched read came back as: a blob's text, nothing at
  * that path, or an object that is not a file (a directory, say). The last

package/src/modules/access-model/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The access model's public entry: what another module imports of it.
+ *
+ * The module is the grammar of `access.md` (how principals, roles, groups
+ * and verbs are spelled), the errors a refused access is reported with, and
+ * the gate a change is read through. A consumer outside the module imports
+ * from here, not from the files; the files are the module's own layout and
+ * free to move. The `access` module's own files predate this entry and still
+ * import the files directly — they move here as they are touched.
+ */
+export * from './access-grammar.js';
+export * from './access-errors.js';
+export type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from './change-gate.js';

package/src/modules/agent-guide/__tests__/agent-guide.test.ts

@@ -358,7 +358,7 @@ describe('the HTML views section', () => {
     expect(ids.indexOf('html-views')).toBe(ids.indexOf('tool-manuals') + 1);
   });
 
-  it('describes the frame, the two members core puts on window.bevel, and a fragment that scrolls the page', async () => {
+  it('describes the frame, the members core puts on window.bevel, and a fragment that scrolls the page', async () => {
     const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
     expect(text).toContain('**No network.**');
     expect(text).toContain('**Inline scripts and styles only.**');
@@ -374,6 +374,27 @@ describe('the HTML views section', () => {
     expect(docs).toContain('/workspace/main/Docs/Alice.md');
   });
 
+  it('documents window.bevel.tools: its four functions, the null check, the consent rule and requireTools with its card', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
+    for (const member of [
+      '`window.bevel.tools.searchTools(query)`',
+      '`window.bevel.tools.toolsInfo(names)`',
+      '`window.bevel.tools.callTool(name, args)`',
+      '`window.bevel.tools.callToolChain(code)`',
+      '`window.bevel.requireTools()`',
+    ]) {
+      expect(text).toContain(member);
+    }
+    expect(text).toContain('`window.bevel.tools` is `null` wherever tools are not available');
+    expect(text).toContain('Check it before every use');
+    expect(text).toContain('**Reading runs at once; writing asks first.**');
+    expect(text).toContain('"<page name> wants to write to the knowledge base"');
+    expect(text).toContain('Allow while open and Deny');
+    expect(text).toContain('rejects the call with `denied`');
+    expect(text).toContain('"<page name> uses tools that are only available in the platform"');
+    expect(text).toContain('Continue without tools and Open in the platform');
+  });
+
   it('lets a distribution replace the section or drop it', async () => {
     const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
       sections.map((s) => (s.id === 'html-views' ? { id: s.id, body: '## HTML views\n\nOurs, graph-aware.\n' } : s)),

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

@@ -3,7 +3,7 @@ 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 { AuditPrincipalNotFoundError, InvalidCursorError, pagePrincipalId, parsePagePrincipalId } 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';
@@ -217,6 +217,8 @@ describe('AgentAuditService.listPrincipals', () => {
           { keyId: 'k-1', connectionId: null, n: 7 },
           { keyId: null, connectionId: 'c-1', n: 3 },
         ],
+        // pages
+        [],
       ],
       { listForUser: vi.fn(async () => [key({ lastUsedAt: NOW - 2 * DAY })]) },
     );
@@ -235,6 +237,7 @@ describe('AgentAuditService.listPrincipals', () => {
       [
         [{ connection: connection({ id: 'c-bob', userId: BOB.id }), user: BOB }],
         [],
+        [],
       ],
       { listForDeployment: vi.fn(async () => [{ ...key({}), user: ALICE }]) },
     );
@@ -247,6 +250,80 @@ describe('AgentAuditService.listPrincipals', () => {
   });
 });
 
+describe('AgentAuditService — a page as a principal', () => {
+  const ALICE_ID = '11111111-1111-4111-8111-111111111111';
+  const PAGE = 'Dashboards/Roadmap.html';
+
+  it("records a page's call under its path, with neither a key nor a connection", async () => {
+    const { service, captured } = makeService([undefined]);
+    service.record({
+      userId: ALICE_ID,
+      principal: { kind: 'page', path: PAGE },
+      kind: 'capability',
+      manual: null,
+      name: 'edit_file',
+      outcome: 'refused',
+      durationMs: null,
+    });
+    await flush();
+    expect(captured.values[0]).toMatchObject({
+      userId: ALICE_ID,
+      keyId: null,
+      connectionId: null,
+      pagePath: PAGE,
+      name: 'edit_file',
+      outcome: 'refused',
+    });
+  });
+
+  it('lists each page a person opened as a row of its own, labelled by its path, never revocable', async () => {
+    const { service } = makeService([
+      [{ ...ALICE, id: ALICE_ID }],
+      [],
+      [],
+      [
+        {
+          userId: ALICE_ID,
+          pagePath: PAGE,
+          n: 4,
+          first: new Date(NOW - DAY),
+          last: new Date(NOW - 60_000),
+          user: { ...ALICE, id: ALICE_ID },
+        },
+      ],
+    ]);
+    const rows = await service.listPrincipals({ userId: ALICE_ID });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      kind: 'page',
+      id: pagePrincipalId(ALICE_ID, PAGE),
+      label: PAGE,
+      eventCount: 4,
+      createdAt: NOW - DAY,
+      lastUsedAt: NOW - 60_000,
+      revokedAt: null,
+    });
+  });
+
+  it("reads a page's events by its person and path, and owns it by that person", async () => {
+    const id = pagePrincipalId(ALICE_ID, PAGE);
+    expect(parsePagePrincipalId(id)).toEqual({ userId: ALICE_ID, path: PAGE });
+
+    const events = makeService([[], [{ total: 0 }]]);
+    await events.service.listEvents({ kind: 'page', id }, { limit: 10 });
+    expect(render(events.captured.where[0]).params).toEqual([ALICE_ID, PAGE]);
+
+    const owned = makeService([[{ id: 'e-1' }]]);
+    await expect(owned.service.ownerOf({ kind: 'page', id })).resolves.toBe(ALICE_ID);
+    const never = makeService([[]]);
+    await expect(never.service.ownerOf({ kind: 'page', id })).resolves.toBeNull();
+    // An id that names no person and path is no page, without asking the database.
+    const bogus = makeService([]);
+    await expect(bogus.service.ownerOf({ kind: 'page', id: 'not-a-page' })).resolves.toBeNull();
+    expect(bogus.counts.select).toBe(0);
+  });
+});
+
 describe('AgentAuditService.listEvents', () => {
   const eventId = (i: number) => `00000000-0000-4000-8000-00000000000${i}`;
   const eventRow = (i: number) => ({

package/src/modules/audit/__tests__/audit.routes.test.ts

@@ -5,6 +5,7 @@ import { createAuditRoutes } from '../audit.routes.js';
 import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,
+  pagePrincipalId,
   type AuditPrincipal,
   type IAgentAuditService,
 } from '../audit.contract.js';
@@ -31,7 +32,9 @@ const ALICE_KEY: AuditPrincipal = {
 };
 
 /** Who owns what, as the fake service answers `ownerOf`. */
-const OWNERS: Record<string, string> = { [KEY_ID]: ALICE.id, [AGENT_ID]: BOB.id, [ALICE_AGENT_ID]: ALICE.id };
+/** A page Alice's views have called tools from; its id names a person by uuid, so it is minted for one. */
+const ALICE_PAGE_ID = pagePrincipalId('33333333-4444-4555-8666-777777777777', 'Dashboards/Roadmap.html');
+const OWNERS: Record<string, string> = { [KEY_ID]: ALICE.id, [AGENT_ID]: BOB.id, [ALICE_AGENT_ID]: ALICE.id, [ALICE_PAGE_ID]: ALICE.id };
 
 const audit = {
   listPrincipals: vi.fn(async () => [ALICE_KEY]),
@@ -103,6 +106,24 @@ describe('audit routes — events', () => {
     expect(audit.listEvents).toHaveBeenCalledWith({ kind: 'key', id: KEY_ID }, { before: '123.e-9', limit: 200 });
   });
 
+  it("serves a page's events to its viewer, and 404s an id that names no page", async () => {
+    const base = await listen(makeApp({ admin: false }));
+    const res = await fetch(`${base}/api/audit/principals/page/${ALICE_PAGE_ID}/events`);
+    expect(res.status).toBe(200);
+    expect(audit.listEvents).toHaveBeenCalledWith({ kind: 'page', id: ALICE_PAGE_ID }, { before: undefined, limit: 50 });
+    const notAPage = await fetch(`${base}/api/audit/principals/page/not-a-page/events`);
+    expect(notAPage.status).toBe(404);
+    expect(await notAPage.json()).toEqual({ error: 'No such agent, key or page' });
+  });
+
+  it('404s a page id whose path carries a line break of any kind', async () => {
+    const base = await listen(makeApp({ admin: false }));
+    for (const brk of ['\n', '\r', '\u0085', '\u2028', '\u2029']) {
+      const id = pagePrincipalId('33333333-4444-4555-8666-777777777777', `Dashboards/Road${brk}map.html`);
+      expect((await fetch(`${base}/api/audit/principals/page/${id}/events`)).status).toBe(404);
+    }
+  });
+
   it('answers a cursor the service does not recognise with 400, not 500', async () => {
     const base = await listen(makeApp({ admin: false }));
     audit.listEvents.mockRejectedValueOnce(new InvalidCursorError());
@@ -110,9 +131,23 @@ describe('audit routes — events', () => {
     expect(res.status).toBe(400);
   });
 
-  it("refuses another person's principal to a member, and serves it to an admin", async () => {
-    const asAlice = await listen(makeApp({ admin: false }));
-    expect((await fetch(`${asAlice}/api/audit/principals/agent/${AGENT_ID}/events`)).status).toBe(403);
+  it("refuses another person's principal to a member exactly as one that does not exist, and serves it to an admin", async () => {
+    const asBob = await listen(makeApp({ admin: false, as: BOB }));
+    const missingPage = pagePrincipalId('33333333-4444-4555-8666-777777777777', 'Dashboards/Nothing.html');
+    const refusals = [];
+    const missing = '00000000-0000-4000-8000-000000000000';
+    for (const path of [
+      `page/${ALICE_PAGE_ID}`,
+      `page/${missingPage}`,
+      `key/${KEY_ID}`,
+      `key/${missing}`,
+      `agent/${ALICE_AGENT_ID}`,
+      `agent/${missing}`,
+    ]) {
+      const res = await fetch(`${asBob}/api/audit/principals/${path}/events`);
+      refusals.push({ status: res.status, body: await res.json() });
+    }
+    expect(refusals).toEqual(Array(6).fill({ status: 404, body: { error: 'No such agent, key or page' } }));
     expect(audit.listEvents).not.toHaveBeenCalled();
     server.close();
 
@@ -166,7 +201,10 @@ describe('audit routes — revoke an agent', () => {
   it('404s when the connection vanished between the ownership check and the revoke', async () => {
     const base = await listen(makeApp({ admin: false, as: BOB }));
     audit.revokeConnection.mockRejectedValueOnce(new AuditPrincipalNotFoundError());
-    expect((await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' })).status).toBe(404);
+    const res = await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' });
+    expect(res.status).toBe(404);
+    // Only an agent revoke throws it, so it names an agent, as the route's other 404s do.
+    expect(await res.json()).toEqual({ error: 'No such agent' });
   });
 });
 

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

@@ -1,4 +1,4 @@
-import { and, count, desc, eq, isNotNull, isNull, lt, or, type SQL } from 'drizzle-orm';
+import { and, count, desc, eq, isNotNull, isNull, lt, max, min, or, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 import type { Database } from '../database/connection.js';
 import { agentConnections, agentEvents, externalApiKeys, oauthTokens, users } from '../database/schema.js';
@@ -7,6 +7,8 @@ import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,
   isUuid,
+  pagePrincipalId,
+  parsePagePrincipalId,
   parseRetentionWindow,
   type AgentEventInput,
   type AgentEventPage,
@@ -59,6 +61,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         userId: event.userId,
         keyId: event.principal.kind === 'key' ? event.principal.id : null,
         connectionId: event.principal.kind === 'agent' ? event.principal.id : null,
+        pagePath: event.principal.kind === 'page' ? event.principal.path : null,
         kind: event.kind,
         manual: event.manual,
         name: event.name,
@@ -93,7 +96,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
 
   async listPrincipals(scope: AuditScope): Promise<AuditPrincipal[]> {
     const mine = scope === 'all' ? null : scope.userId;
-    const [keyRows, connectionRows, countRows] = await Promise.all([
+    const [keyRows, connectionRows, countRows, pageRows] = await Promise.all([
       mine === null ? this.keys.listForDeployment() : this.keysForUser(mine),
       this.db
         .select({
@@ -111,6 +114,22 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         .from(agentEvents)
         .where(mine === null ? undefined : eq(agentEvents.userId, mine))
         .groupBy(agentEvents.keyId, agentEvents.connectionId),
+      // A page has no row of its own: it is every event recorded under one
+      // person and one path, so its "created" is its first call and its
+      // "last used" its latest.
+      this.db
+        .select({
+          userId: agentEvents.userId,
+          pagePath: agentEvents.pagePath,
+          n: count(),
+          first: min(agentEvents.at),
+          last: max(agentEvents.at),
+          user: { id: users.id, email: users.email, name: users.name },
+        })
+        .from(agentEvents)
+        .innerJoin(users, eq(agentEvents.userId, users.id))
+        .where(and(isNotNull(agentEvents.pagePath), mine === null ? undefined : eq(agentEvents.userId, mine)))
+        .groupBy(agentEvents.userId, agentEvents.pagePath, users.id, users.email, users.name),
     ]);
 
     const counts = new Map<string, number>();
@@ -144,6 +163,24 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         eventCount: counts.get(c.id) ?? 0,
         user,
       })),
+      ...pageRows.flatMap((r) =>
+        r.pagePath
+          ? [
+              {
+                kind: 'page' as const,
+                id: pagePrincipalId(r.userId, r.pagePath),
+                label: r.pagePath,
+                createdAt: toMs(r.first),
+                lastUsedAt: r.last ? toMs(r.last) : null,
+                // A page cannot be revoked: it acts only while its viewer has it open.
+                revokedAt: null,
+                revokedBy: null,
+                eventCount: Number(r.n),
+                user: r.user,
+              },
+            ]
+          : [],
+      ),
     ];
     // Per account (by email), live before revoked, most recently used first,
     // newest first among the never-used — the order the page shows without
@@ -175,6 +212,17 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
   }
 
   async ownerOf(principal: AuditPrincipalRef): Promise<string | null> {
+    if (principal.kind === 'page') {
+      // The person is in the id; the page exists for them once it has called something.
+      const page = parsePagePrincipalId(principal.id);
+      if (!page) return null;
+      const [row] = await this.db
+        .select({ id: agentEvents.id })
+        .from(agentEvents)
+        .where(and(eq(agentEvents.userId, page.userId), eq(agentEvents.pagePath, page.path)))
+        .limit(1);
+      return row ? page.userId : null;
+    }
     if (principal.kind === 'agent') {
       const [row] = await this.db
         .select({ userId: agentConnections.userId })
@@ -192,10 +240,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
     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);
+    const byPrincipal = principalFilter(principal);
     // 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.
@@ -340,6 +385,21 @@ function formatCursor(at: Date, id: string): string {
  * compare it with anything else) and the instant a whole number of epoch
  * milliseconds a `timestamp` can hold.
  */
+/** The events of one principal. A page id that names no page matches nothing. */
+function principalFilter(principal: AuditPrincipalRef): SQL {
+  if (principal.kind === 'key') return eq(agentEvents.keyId, principal.id);
+  if (principal.kind === 'agent') return eq(agentEvents.connectionId, principal.id);
+  const page = parsePagePrincipalId(principal.id);
+  if (!page) return isNull(agentEvents.id);
+  return and(eq(agentEvents.userId, page.userId), eq(agentEvents.pagePath, page.path))!;
+}
+
+/** An aggregate's timestamp, which a driver may hand back as a Date or as the text Postgres sent. */
+function toMs(value: Date | string | null): number {
+  if (value === null) return 0;
+  return value instanceof Date ? value.getTime() : new Date(value).getTime();
+}
+
 function parseCursor(raw: string): { at: Date; id: string } | null {
   const dot = raw.indexOf('.');
   if (dot < 0) return null;

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

@@ -24,19 +24,71 @@ declare global {
 /** 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';
+/**
+ * How the call ended. `denied`: the caller's sign-in for the tool was
+ * missing, so nothing ran. `refused`: a page made a call that needs the
+ * viewer's approval (a writing tool, a tool the manual does not list, or a
+ * chain) and the person viewing it answered Deny, so nothing ran.
+ */
+export type AgentEventOutcome = 'ok' | 'error' | 'denied' | 'refused';
 
 /**
  * Who a call is attributed to: the connection key it was authenticated with,
- * or the agent connection behind its OAuth grant. Exactly one.
+ * the agent connection behind its OAuth grant, or the knowledge-base page
+ * whose script made it as the person viewing it. Exactly one.
+ *
+ * A page has no row of its own: it is a person and a path, and its `id` is
+ * both, encoded by {@link pagePrincipalId} so the Audit log's routes can name
+ * it like the other two.
+ */
+export type AuditPrincipalRef = { kind: 'key'; id: string } | { kind: 'agent'; id: string } | { kind: 'page'; id: string };
+
+/** Who a call is attributed to, as the recorder takes it: a page by its path, the recorder knows the person. */
+export type RecordedPrincipal = { kind: 'key'; id: string } | { kind: 'agent'; id: string } | { kind: 'page'; path: string };
+
+/** The longest page path a page principal may carry. A path is a file in the knowledge base, never longer. */
+export const MAX_PAGE_PATH_LENGTH = 1024;
+
+/**
+ * A page principal's id: the person and the page's path, encoded so it is one
+ * URL segment. Opaque to the client, which only ever echoes it back.
  */
-export type AuditPrincipalRef = { kind: 'key'; id: string } | { kind: 'agent'; id: string };
+export function pagePrincipalId(userId: string, path: string): string {
+  return Buffer.from(`${userId}\n${path}`, 'utf8').toString('base64url');
+}
+
+/** The person and the path a page principal's id names, or null when it names none. */
+export function parsePagePrincipalId(id: string): { userId: string; path: string } | null {
+  if (!/^[A-Za-z0-9_-]+$/.test(id)) return null;
+  const decoded = Buffer.from(id, 'base64url').toString('utf8');
+  const cut = decoded.indexOf('\n');
+  if (cut < 0) return null;
+  const userId = decoded.slice(0, cut);
+  const path = decoded.slice(cut + 1);
+  if (!isUuid(userId) || !isPagePath(path)) return null;
+  return { userId, path };
+}
+
+/**
+ * Whether `path` can be a page principal: a non-empty knowledge-base path of
+ * printable characters, bounded. A page names itself through a request
+ * header, so this is the check that keeps a line break or a control character
+ * out of the log and its listing — the C1 controls (NEL among them) and the
+ * Unicode line and paragraph separators included.
+ */
+export function isPagePath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    path.length <= MAX_PAGE_PATH_LENGTH &&
+    // eslint-disable-next-line no-control-regex -- the point is to refuse control characters
+    !/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/.test(path)
+  );
+}
 
 /** One recorded call, as the recorder takes it. */
 export interface AgentEventInput {
   userId: string;
-  principal: AuditPrincipalRef;
+  principal: RecordedPrincipal;
   kind: AgentEventKind;
   /** The MCP server / `.tool` manual for a tool, the skill folder for a skill; null for a capability. */
   manual: string | null;
@@ -54,18 +106,18 @@ export interface IAgentEventRecorder {
   record(event: AgentEventInput): void;
 }
 
-/** One row of the Audit log: an agent connection or a connection key, with its owner. */
+/** One row of the Audit log: an agent connection, a connection key or a page, with its owner. */
 export interface AuditPrincipal {
-  kind: 'key' | 'agent';
+  kind: 'key' | 'agent' | 'page';
   id: string;
-  /** The key's label, or the agent's registered client name. */
+  /** The key's label, the agent's registered client name, or the page's knowledge-base path. */
   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. */
+  /** When the key was created / the agent connected / the page first called a tool. Epoch ms. */
   createdAt: number;
   lastUsedAt: number | null;
   revokedAt: number | null;
@@ -149,7 +201,7 @@ export interface IAgentConnectionStatus {
 
 export class AuditPrincipalNotFoundError extends Error {
   constructor() {
-    super('No such agent or key');
+    super('No such agent');
     this.name = 'AuditPrincipalNotFoundError';
   }
 }