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

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -20,6 +20,7 @@ import type {
   OAuthTokenRevocationRequest,
   OAuthTokens,
 } from '@modelcontextprotocol/sdk/shared/auth.js';
+import type { AgentConnectedEvent } from '@bevel-software/platform-shared';
 import type { Database } from '../../database/connection.js';
 import { agentConnections, oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/schema.js';
 import type { TokenCrypto } from '../../../shared/token-crypto.js';
@@ -57,6 +58,12 @@ export interface BevelOAuthProviderDeps {
   publicFrontendUrl: string;
   /** Access-token plaintext prefix, e.g. `bevel-mcp_`. */
   tokenPrefix: string;
+  /**
+   * Where the FIRST use of an agent connection is announced to its owner
+   * (`agent-connected`, see {@link BevelOAuthProvider.noteConnectionUse}).
+   * Optional: without it the stamp is written and nobody is told.
+   */
+  events?: { emit(event: AgentConnectedEvent): void };
 }
 
 /**
@@ -511,11 +518,42 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     const last = this.connectionTouchedAt.get(connectionId);
     if (last !== undefined && now - last < CONNECTION_TOUCH_INTERVAL_MS) return;
     this.connectionTouchedAt.set(connectionId, now);
-    this.deps.db
+    this.stampConnectionUse(connectionId, new Date(now)).catch((err) =>
+      log.warn('touch connection lastUsedAt failed:', { err }),
+    );
+  }
+
+  /**
+   * The stamp itself, and the one thing it tells: a connection stamped for
+   * the FIRST time is an agent that has just reached the platform — the
+   * `initialize` every client sends on connecting — which is what the
+   * onboarding waits for, so its owner is told (`agent-connected`) for
+   * exactly that stamp and never again.
+   *
+   * The first stamp is CLAIMED in one statement (`… where last_used_at is
+   * null … returning`): of two requests racing it — a parallel
+   * `initialize` and `tools/list`, or two replicas — the database hands the
+   * row to exactly one, and only that one announces. The loser, and every
+   * later use, stamps the ordinary way. Both sit behind the throttle above,
+   * so the hot path pays nothing for them.
+   */
+  private async stampConnectionUse(connectionId: string, at: Date): Promise<void> {
+    const [first] = await this.deps.db
       .update(agentConnections)
-      .set({ lastUsedAt: new Date(now) })
-      .where(eq(agentConnections.id, connectionId))
-      .then(undefined, (err) => log.warn('touch connection lastUsedAt failed:', { err }));
+      .set({ lastUsedAt: at })
+      .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.lastUsedAt)))
+      .returning({ userId: agentConnections.userId, client: agentConnections.clientName });
+    if (first) {
+      this.deps.events?.emit({
+        kind: 'agent-connected',
+        forUserId: first.userId,
+        client: first.client ?? 'Unnamed agent',
+        agentKind: 'agent',
+        at: at.toISOString(),
+      });
+      return;
+    }
+    await this.deps.db.update(agentConnections).set({ lastUsedAt: at }).where(eq(agentConnections.id, connectionId));
   }
 
   /**

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

@@ -0,0 +1,163 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { createOnboardingRoutes } from '../onboarding.routes.js';
+import type { IStarterPackService } from '../onboarding.contract.js';
+import { StarterPackError } from '../starter-pack.service.js';
+
+/**
+ * The two starter-pack routes: the caller is the session's, the GET is never
+ * cached, refusals keep their status and words, and a lock held elsewhere is
+ * a 409 to try again rather than a 500.
+ */
+
+const ADA: AuthUser = { id: 'u-ada', email: 'ada@example.com', name: 'Ada' } as AuthUser;
+
+let server: Server | undefined;
+afterEach(() => {
+  server?.close();
+  server = undefined;
+});
+
+async function listen(
+  svc: IStarterPackService,
+  as: AuthUser | null | (() => Promise<AuthUser | null>) = ADA,
+): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createOnboardingRoutes(svc, typeof as === 'function' ? as : async () => as));
+  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 = (url: string, body: unknown) =>
+  fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+
+describe('GET /onboarding/starter-packs', () => {
+  it('answers for the caller, uncached', async () => {
+    const answer = { offered: true, chosen: null, packs: [], chosenPack: null };
+    const svc = { status: vi.fn(async () => answer), choose: vi.fn() };
+    const base = await listen(svc);
+    const res = await fetch(`${base}/api/onboarding/starter-packs`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('cache-control')).toBe('no-store');
+    expect(await res.json()).toEqual(answer);
+    expect(svc.status).toHaveBeenCalledWith(ADA);
+  });
+
+  it('is 401 without a user', async () => {
+    const base = await listen({ status: vi.fn(), choose: vi.fn() }, null);
+    expect((await fetch(`${base}/api/onboarding/starter-packs`)).status).toBe(401);
+  });
+
+  it('is 500, not 401, when the caller could not be looked up: an outage is not an expired session', async () => {
+    const svc = { status: vi.fn(), choose: vi.fn() };
+    const base = await listen(svc, async () => {
+      throw new Error('database unreachable');
+    });
+    const res = await fetch(`${base}/api/onboarding/starter-packs`);
+    expect(res.status).toBe(500);
+    expect((await res.json()).error).toMatch(/who is signed in/i);
+    expect(svc.status).not.toHaveBeenCalled();
+  });
+
+  it('is 500 when the answer could not be had', async () => {
+    const svc = {
+      status: vi.fn(async () => {
+        throw new Error('packs folder unreadable');
+      }),
+      choose: vi.fn(),
+    };
+    const base = await listen(svc);
+    const res = await fetch(`${base}/api/onboarding/starter-packs`);
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({ error: 'Could not load the starter packs' });
+  });
+});
+
+describe('POST /onboarding/starter-pack', () => {
+  it('chooses as the caller', async () => {
+    const applied = { id: 'sales', name: 'Sales', pages: 2, skills: 3, summary: 'Added 2 pages and 3 skills for Sales.' };
+    const svc = { status: vi.fn(), choose: vi.fn(async () => applied) };
+    const base = await listen(svc);
+    const res = await post(`${base}/api/onboarding/starter-pack`, { id: 'sales' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual(applied);
+    expect(svc.choose).toHaveBeenCalledWith(ADA, 'sales');
+  });
+
+  it('passes "none" through as the skip it is', async () => {
+    const skipped = { id: 'none', name: null, pages: 0, skills: 0, summary: '' };
+    const svc = { status: vi.fn(), choose: vi.fn(async () => skipped) };
+    const base = await listen(svc);
+    const res = await post(`${base}/api/onboarding/starter-pack`, { id: 'none' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual(skipped);
+    expect(svc.choose).toHaveBeenCalledWith(ADA, 'none');
+  });
+
+  it('needs an id', async () => {
+    const base = await listen({ status: vi.fn(), choose: vi.fn() });
+    expect((await post(`${base}/api/onboarding/starter-pack`, {})).status).toBe(400);
+  });
+
+  it('is 401 without a user, and 500 when the caller could not be looked up', async () => {
+    const svc = { status: vi.fn(), choose: vi.fn() };
+    const anonymous = await listen(svc, null);
+    expect((await post(`${anonymous}/api/onboarding/starter-pack`, { id: 'sales' })).status).toBe(401);
+    server?.close();
+    const outage = await listen(svc, async () => {
+      throw new Error('database unreachable');
+    });
+    expect((await post(`${outage}/api/onboarding/starter-pack`, { id: 'sales' })).status).toBe(500);
+    expect(svc.choose).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    [403, 'Only an admin can add starter pages.'],
+    [404, 'There is no starter pack "astronomy".'],
+    [409, 'Starter pages were already chosen for this knowledge base.'],
+  ])('passes a refusal through with its status: %i', async (status, message) => {
+    const svc = {
+      status: vi.fn(),
+      choose: vi.fn(async () => {
+        throw new StarterPackError(message, status);
+      }),
+    };
+    const base = await listen(svc);
+    const res = await post(`${base}/api/onboarding/starter-pack`, { id: 'sales' });
+    expect(res.status).toBe(status);
+    expect(await res.json()).toEqual({ error: message });
+  });
+
+  it('says nothing was changed, in its own words, when the write failed for a reason of its own', async () => {
+    const svc = {
+      status: vi.fn(),
+      choose: vi.fn(async () => {
+        throw new Error('ENOSPC: no space left on device');
+      }),
+    };
+    const base = await listen(svc);
+    const res = await post(`${base}/api/onboarding/starter-pack`, { id: 'sales' });
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({ error: 'Could not add the starter pages. Nothing was changed.' });
+  });
+
+  it('turns a path locked by someone else into a 409 to retry', async () => {
+    const svc = {
+      status: vi.fn(),
+      choose: vi.fn(async () => {
+        throw new Error('Skipped editing "kb/KnowledgeBase/About us.md" — locked by Bo. Continuing with other edits; try this one again later.');
+      }),
+    };
+    const base = await listen(svc);
+    const res = await post(`${base}/api/onboarding/starter-pack`, { id: 'sales' });
+    expect(res.status).toBe(409);
+    expect((await res.json()).error).toMatch(/try again/i);
+  });
+});