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

package/src/modules/mcp/__tests__/mcp-routes-harness.ts

@@ -29,6 +29,12 @@ import type { McpCallerKind } from '../mcp-auth.middleware.js';
  */
 export const fakeAuth: RequestHandler = (req, _res, next) => {
   req.userId = (req.headers['x-test-user'] as string | undefined) ?? 'user-A';
+  // The signed-in person's email, for a suite whose route reads it.
+  const email = req.headers['x-test-email'] as string | undefined;
+  if (email) req.userEmail = email;
+  // The agent the credential connects as, as the real middleware sets it.
+  const agentPath = req.headers['x-test-agent-path'] as string | undefined;
+  if (agentPath) req.mcpAgentPath = agentPath;
   // The credential kind the real middleware would have recognised, when a
   // suite needs one (the page header is a session's alone).
   const kind = req.headers['x-test-kind'] as McpCallerKind | undefined;
@@ -48,6 +54,7 @@ export interface McpRoutesDeps {
   internalTokens?: unknown;
   oauthProvider?: unknown;
   resourceMetadataUrl?: string;
+  agents?: unknown;
 }
 
 /** Servers opened by `mountMcpRoutes`, closed together by `closeMountedRoutes`. */
@@ -73,6 +80,7 @@ export async function mountMcpRoutes(deps: McpRoutesDeps = {}): Promise<string>
       (deps.internalTokens ?? stub) as never,
       (deps.oauthProvider ?? stub) as never,
       deps.resourceMetadataUrl ?? '',
+      deps.agents as never,
     ),
   );
   const server = await new Promise<HttpServer>((resolve) => {

package/src/modules/mcp/__tests__/mcp.connect-as.test.ts

@@ -0,0 +1,195 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CONNECTION_META_KEY, McpService, type McpCaller } from '../mcp.service.js';
+import { SpillStore } from '../../workspace/index.js';
+import { createManualRoutes } from '../../tool-registry/manual.routes.js';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { toolDef } from '../../tool-helpers/index.js';
+import type { ConnectionScopeWire } from '../../agent-scope/index.js';
+
+/**
+ * The MCP proxy's half of connecting as an agent. The surfaces behind the
+ * loopback do the narrowing (pinned in the agent-scope suites); what the proxy
+ * owns is the WORDING and the CACHE: a tool off a narrowed surface is refused
+ * by name and agent rather than as unknown, a connection whose file is gone is
+ * served an empty listing with the reason, the handshake says what the
+ * connection is connected as, and two connections of one person made as
+ * different agents never share a built surface.
+ *
+ * The loopback here answers each bearer as the agent surfaces would answer
+ * that credential: `bevel_all` is Everything, `bevel_narrow` an agent that
+ * loads `read_file` alone, `bevel_gone` one whose file was deleted.
+ */
+
+const NARROW: ConnectionScopeWire = { agent: { path: 'Agents/narrow.agent', name: 'narrow' } };
+const GONE: ConnectionScopeWire = {
+  agent: { path: 'Agents/gone.agent', name: 'Agents/gone.agent' },
+  unavailable: 'This connection was made as the agent file `Agents/gone.agent`, which no longer exists.',
+};
+const CONNECTIONS: Record<string, ConnectionScopeWire | undefined> = {
+  bevel_all: undefined,
+  bevel_narrow: NARROW,
+  bevel_gone: GONE,
+};
+
+let httpServer: HttpServer | undefined;
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const c of cleanups.splice(0)) await c().catch(() => {});
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.restoreAllMocks();
+});
+
+async function harness() {
+  const state = { builds: 0, base: '' };
+  const connectionOf = (req: express.Request) => CONNECTIONS[(req.headers.authorization ?? '').replace(/^Bearer /, '')];
+  const registry = new ToolRegistry();
+  for (const name of ['read_file', 'edit_file']) {
+    registry.registerExternalTool(
+      toolDef({ name, description: name, path: `/api/agent/tools/${name}`, inputs: { type: 'object', properties: {} } }),
+    );
+  }
+  const app = express();
+  app.use(express.json());
+  app.get('/api/agent/catalog-revision', (req, res) => {
+    const connection = connectionOf(req);
+    res.json({ revision: 'rev-1', tools: 0, skills: 0, ...(connection ? { connection } : {}) });
+  });
+  app.get('/api/agent/all-tools', (req, res) => {
+    state.builds += 1;
+    const connection = connectionOf(req);
+    res.json({ manuals: [], ...(connection ? { connection } : {}) });
+  });
+  // The platform manual, as the agent surfaces narrow it per credential.
+  app.get('/api/agent/utcp', (req, res, next) => {
+    const connection = connectionOf(req);
+    if (!connection) return next();
+    res.json({
+      utcp_version: '1.1.0',
+      manual_version: '1.0.0',
+      tools: connection.unavailable
+        ? []
+        : [
+            {
+              name: 'read_file',
+              description: 'read_file',
+              inputs: { type: 'object', properties: {} },
+              outputs: { type: 'object', properties: {} },
+              tags: [],
+              tool_call_template: {
+                call_template_type: 'http',
+                http_method: 'POST',
+                url: `${state.base}/api/agent/tools/read_file`,
+                content_type: 'application/json',
+              },
+            },
+          ],
+    });
+  });
+  app.use('/api', createManualRoutes(registry, (_req, _res, next) => next()));
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  state.base = `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+  const mcp = new McpService({
+    loopbackBaseUrl: state.base,
+    manualName: 'KNOWLEDGE_BASE',
+    spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    publicFrontendUrl: 'http://localhost:5173',
+  });
+  return { state, mcp };
+}
+
+async function connect(mcp: McpService, caller: Partial<McpCaller>, initialize = false): Promise<Client> {
+  const message = initialize
+    ? { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 't', version: '0' } } }
+    : { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} };
+  const server = await mcp.createRequestServer(
+    { userId: 'user-A', tokenId: 'key-1', connectionId: null, bearer: 'bevel_all', ...caller },
+    message,
+  );
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  const client = new Client({ name: 'test-client', version: '0.0.0' }, { capabilities: {} });
+  await client.connect(clientTransport);
+  cleanups.push(async () => {
+    await client.close();
+    await server.close();
+  });
+  return client;
+}
+
+const textOf = (res: Awaited<ReturnType<Client['callTool']>>) =>
+  (res.content as { type: string; text?: string }[]).find((c) => c.type === 'text')?.text;
+
+describe('a narrowed connection', () => {
+  it('lists what its agent loads, and refuses another tool by name and agent — not as unknown', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const client = await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' });
+    const names = (await client.listTools()).tools.map((t) => t.name);
+    expect(names).toContain('read_file');
+    expect(names).not.toContain('edit_file');
+    const refused = await client.callTool({ name: 'edit_file', arguments: {} });
+    expect(refused.isError).toBe(true);
+    expect(textOf(refused)).toBe(
+      'The tool "edit_file" is not available to this connection: it is connected as the agent "narrow" ' +
+        '(`Agents/narrow.agent`), which does not load it.',
+    );
+  });
+
+  it('Everything still answers an unknown tool as unknown', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const client = await connect(mcp, {});
+    expect((await client.listTools()).tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining(['read_file', 'edit_file']),
+    );
+    expect(textOf(await client.callTool({ name: 'nope', arguments: {} }))).toBe('Unknown tool "nope".');
+  });
+
+  it('tells the agent at the handshake what it is connected as; Everything is told what it always was', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const narrowed = (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' }, true)).getInstructions();
+    const everything = (await connect(mcp, {}, true)).getInstructions();
+    expect(narrowed).toBe(
+      `${everything}\n\nThis connection is connected as the agent "narrow" (\`Agents/narrow.agent\`): it loads only the ` +
+        'platform tools, connectors, skills and plugins that file lists, and of those only what you may read.',
+    );
+    expect(everything).not.toContain('connected as the agent');
+  });
+
+  it('two connections of one person made as different agents never share a built surface', async () => {
+    const { state, mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    await (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' })).listTools();
+    await (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/other.agent' })).listTools();
+    await (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' })).listTools();
+    expect(state.builds).toBe(2);
+  });
+});
+
+describe('a connection whose agent file is gone', () => {
+  it('is served an empty listing carrying the reason, and every call — meta-tools too — answers it', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const client = await connect(mcp, { bearer: 'bevel_gone', agentPath: 'Agents/gone.agent' });
+    const listed = await client.listTools();
+    expect(listed.tools).toEqual([]);
+    expect(listed._meta).toEqual({ [CONNECTION_META_KEY]: GONE.unavailable });
+    for (const name of ['read_file', 'call_tool_chain']) {
+      const res = await client.callTool({ name, arguments: {} });
+      expect(res.isError).toBe(true);
+      expect(textOf(res)).toBe(GONE.unavailable);
+    }
+    const instructions = (await connect(mcp, { bearer: 'bevel_gone', agentPath: 'Agents/gone.agent' }, true)).getInstructions();
+    expect(instructions?.endsWith(GONE.unavailable!)).toBe(true);
+  });
+});

package/src/modules/mcp/__tests__/mcp.routes.connect-as.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createTokenVerifier } from '../../tool-auth/tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+import type { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import { NOT_AN_AGENT_CHOICE } from '../oauth/oauth-consent.routes.js';
+import { agentFile, agentScopeOver, inMemoryKb } from '../../agent-scope/__tests__/in-memory-kb.js';
+import { closeMountedRoutes, mountMcpRoutes } from './mcp-routes-harness.js';
+
+/**
+ * Connecting as an agent on the MCP router: the key-mint path takes the same
+ * "Connect as" choice the consent step does, the dialog is told the same
+ * agents, the local server's exchanged grant carries the connection's agent,
+ * and every MCP request hands the proxy the agent its credential connects as.
+ */
+
+const ADA = 'ada@example.com';
+const kb = inMemoryKb({
+  'Agents/ops.agent': agentFile('name: ops\ndescription: Watches the dashboards.'),
+  'Agents/secret.agent': agentFile('name: secret'),
+});
+kb.hidden.add('Agents/secret.agent');
+
+afterEach(async () => {
+  await closeMountedRoutes();
+  vi.restoreAllMocks();
+});
+
+function keyService() {
+  const mint = vi.fn(async (_userId: string, label: string, options?: { agentPath?: string }) => ({
+    plaintext: 'bevel_new',
+    summary: { id: 'k1', label, agentPath: options?.agentPath ?? null },
+  }));
+  return {
+    service: { looksLikeExternalApiKey: (t: string) => t.startsWith('bevel_'), mint } as unknown as IExternalApiKeyService,
+    mint,
+  };
+}
+
+const post = (url: string, body: unknown) =>
+  fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-test-email': ADA },
+    body: JSON.stringify(body),
+  });
+
+describe('minting a connection key', () => {
+  it('as Everything: no choice is minted exactly as before', async () => {
+    const { service, mint } = keyService();
+    const base = await mountMcpRoutes({ externalApiKeyService: service, agents: agentScopeOver(kb) });
+    const res = await post(`${base}/api/mcp/external-api-keys`, { label: 'laptop' });
+    expect(res.status).toBe(200);
+    expect(mint).toHaveBeenCalledWith('user-A', 'laptop', {});
+  });
+
+  it('as an agent on offer: the key records its normalized path', async () => {
+    const { service, mint } = keyService();
+    const base = await mountMcpRoutes({ externalApiKeyService: service, agents: agentScopeOver(kb) });
+    const res = await post(`${base}/api/mcp/external-api-keys`, { label: 'pipeline', agentPath: 'Agents/ops.agent/' });
+    expect(res.status).toBe(200);
+    expect(mint).toHaveBeenCalledWith('user-A', 'pipeline', { agentPath: 'Agents/ops.agent' });
+    expect(((await res.json()) as { summary: { agentPath: string } }).summary.agentPath).toBe('Agents/ops.agent');
+  });
+
+  it.each([['Agents/secret.agent'], ['Agents/none.agent'], [7]])('refuses %s, minting nothing', async (agentPath) => {
+    const { service, mint } = keyService();
+    const base = await mountMcpRoutes({ externalApiKeyService: service, agents: agentScopeOver(kb) });
+    const res = await post(`${base}/api/mcp/external-api-keys`, { label: 'x', agentPath });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({ error: NOT_AN_AGENT_CHOICE });
+    expect(mint).not.toHaveBeenCalled();
+  });
+
+  it('offers the same agents the consent step does', async () => {
+    const base = await mountMcpRoutes({ agents: agentScopeOver(kb) });
+    const res = await fetch(`${base}/api/mcp/agent-choices`, { headers: { 'x-test-email': ADA } });
+    expect(await res.json()).toEqual({
+      agents: [{ path: 'Agents/ops.agent', name: 'ops', description: 'Watches the dashboards.' }],
+    });
+  });
+
+  it('answers a failed listing as a failure, never as "no agents"', async () => {
+    const failing = { listChoices: async () => Promise.reject(new Error('clone failed')), choosable: async () => null };
+    const base = await mountMcpRoutes({ agents: failing });
+    const res = await fetch(`${base}/api/mcp/agent-choices`, { headers: { 'x-test-email': ADA } });
+    expect(res.status).toBe(500);
+    expect(await res.json()).not.toHaveProperty('agents');
+  });
+});
+
+describe('the local server’s exchanged grant', () => {
+  it("carries the connection's agent, so its calls narrow exactly as the hosted endpoint's", async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const oauth = {
+      looksLikeAccessToken: (t: string) => t.startsWith('bevel-mcp_'),
+      verifyAccessToken: async () => ({
+        extra: { userId: 'user-5', userEmail: ADA, connectionId: 'conn-9', agentPath: 'Agents/ops.agent' },
+        expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      }),
+    } as unknown as BevelOAuthProvider;
+    const base = await mountMcpRoutes({
+      externalApiKeyService: { looksLikeExternalApiKey: () => false } as never,
+      internalTokens,
+      oauthProvider: oauth,
+    });
+    const res = await fetch(`${base}/api/mcp/local-token`, {
+      method: 'POST',
+      headers: { Authorization: 'Bearer bevel-mcp_grant' },
+    });
+    const { token } = (await res.json()) as { token: string };
+    const verify = createTokenVerifier({ looksLikeExternalApiKey: () => false } as never, internalTokens);
+    expect(await verify(token)).toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', agentPath: 'Agents/ops.agent', scope: 'write' },
+    });
+  });
+
+  it('an Everything grant mints the token it always did', async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const oauth = {
+      looksLikeAccessToken: (t: string) => t.startsWith('bevel-mcp_'),
+      verifyAccessToken: async () => ({
+        extra: { userId: 'user-5', userEmail: ADA, connectionId: 'conn-9', agentPath: null },
+        expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      }),
+    } as unknown as BevelOAuthProvider;
+    const base = await mountMcpRoutes({
+      externalApiKeyService: { looksLikeExternalApiKey: () => false } as never,
+      internalTokens,
+      oauthProvider: oauth,
+    });
+    const res = await fetch(`${base}/api/mcp/local-token`, { method: 'POST', headers: { Authorization: 'Bearer bevel-mcp_g' } });
+    const { token } = (await res.json()) as { token: string };
+    expect(internalTokens.verify(token)).toEqual({ userId: 'user-5', externalProxy: true, connectionId: 'conn-9' });
+  });
+
+  it("a direct tool call reads the connection's CURRENT choice: a re-consent reaches a token minted before it", async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const keys = { looksLikeExternalApiKey: () => false } as never;
+    let current: { agentPath: string | null } | null = { agentPath: 'Agents/ops.agent' };
+    const verify = createTokenVerifier(keys, internalTokens, undefined, {
+      liveConnectionChoice: async (id) => (id === 'conn-9' ? current : null),
+    });
+    // Minted as Everything, served as the agent chosen since.
+    const everything = internalTokens.mint({ userId: 'user-5', externalProxy: true, connectionId: 'conn-9' }, 60_000);
+    expect(await verify(everything)).toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', agentPath: 'Agents/ops.agent', scope: 'write' },
+    });
+    // Minted as an agent, served as Everything once the person chose it.
+    current = { agentPath: null };
+    const asAgent = internalTokens.mint(
+      { userId: 'user-5', externalProxy: true, connectionId: 'conn-9', agentPath: 'Agents/ops.agent' },
+      60_000,
+    );
+    expect(await verify(asAgent)).toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', scope: 'write' },
+    });
+  });
+
+  it("refuses a direct tool call through a revoked connection's token, whatever the token says it connects as", async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const keys = { looksLikeExternalApiKey: () => false } as never;
+    const verify = createTokenVerifier(keys, internalTokens, undefined, { liveConnectionChoice: async () => null });
+    const token = internalTokens.mint(
+      { userId: 'user-5', externalProxy: true, connectionId: 'conn-9', agentPath: 'Agents/ops.agent' },
+      60_000,
+    );
+    expect(await verify(token)).toEqual({ ok: false, status: 401, message: 'Access for this agent was revoked' });
+  });
+});
+
+describe('an MCP request', () => {
+  it("hands the proxy the agent its credential connects as — and nothing for Everything", async () => {
+    const createRequestServer = vi.fn(async () => {
+      throw new Error('stop here');
+    });
+    const base = await mountMcpRoutes({ mcpService: { createRequestServer } });
+    const call = (headers: Record<string, string>) =>
+      fetch(`${base}/api/mcp`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...headers },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
+      });
+    await call({ 'x-test-agent-path': 'Agents/ops.agent' });
+    await call({});
+    const callers = createRequestServer.mock.calls.map((c) => (c as unknown[])[0] as Record<string, unknown>);
+    expect(callers[0]).toMatchObject({ userId: 'user-A', agentPath: 'Agents/ops.agent' });
+    expect(callers[1]).not.toHaveProperty('agentPath');
+  });
+});

package/src/modules/mcp/__tests__/oauth-consent.connect-as.test.ts

@@ -0,0 +1,146 @@
+import express from 'express';
+import type { AddressInfo } from 'node:net';
+import type { Server } from 'node:http';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createOAuthConsentRoutes, NOT_AN_AGENT_CHOICE } from '../oauth/oauth-consent.routes.js';
+import { signAuthRequest } from '../oauth/oauth-state.js';
+import { agentFile, agentScopeOver, inMemoryKb } from '../../agent-scope/__tests__/in-memory-kb.js';
+
+/**
+ * The consent step's "Connect as" choice, through the two routes the
+ * /connect page calls: the request description offers the agents the person
+ * may read, and Finish hands the provider exactly the choice made — null for
+ * Everything — or refuses one that is not on offer, before any code is minted.
+ * The choice offered and checked is the REAL agent-scope service's, over a
+ * knowledge base held in memory.
+ */
+
+const SECRET = 'state-secret';
+const ADA = 'ada@example.com';
+
+let http: Server | null = null;
+afterEach(async () => {
+  if (http) await new Promise<void>((r) => http!.close(() => r()));
+  http = null;
+});
+
+const kb = inMemoryKb({
+  'Agents/mechanic.agent': agentFile('name: delivery-mechanic\ndescription: Moves code around.'),
+  'Agents/secret.agent': agentFile('name: secret'),
+});
+kb.hidden.add('Agents/secret.agent');
+
+async function mount(opts: { email?: string; agents?: Parameters<typeof createOAuthConsentRoutes>[0]['agents'] } = {}) {
+  const issueAuthCode = vi.fn(async () => ({ redirectTo: 'https://agent.example.com/cb?code=c1' }));
+  const completeConsent = vi.fn(async () => ({ redirectTo: 'https://claude.ai/cb?code=gh' }));
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userId = 'u1';
+    req.userEmail = opts.email ?? ADA;
+    next();
+  });
+  app.use(
+    createOAuthConsentRoutes({
+      provider: {
+        issueAuthCode,
+        clientsStore: { getClient: async () => ({ client_name: 'Claude' }) },
+      } as never,
+      stateSecret: SECRET,
+      facade: {
+        isFacadeRequest: () => true,
+        clientNameFor: () => 'Claude',
+        completeConsent,
+      },
+      agents: opts.agents ?? agentScopeOver(kb),
+    }),
+  );
+  http = app.listen(0);
+  await new Promise<void>((r) => http!.once('listening', r));
+  const base = `http://127.0.0.1:${(http.address() as AddressInfo).port}`;
+  return { base, issueAuthCode, completeConsent };
+}
+
+const state = (extra: Record<string, unknown> = {}) =>
+  signAuthRequest(SECRET, { c: 'client-1', r: 'https://agent.example.com/cb', cc: 'challenge', ...extra });
+
+async function finish(base: string, body: Record<string, unknown>) {
+  return fetch(`${base}/mcp/oauth/complete`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+describe('the consent step offers "Connect as"', () => {
+  it('lists the agents the person may read, by name with description and path — Everything is the page’s own', async () => {
+    const { base } = await mount();
+    const res = await fetch(`${base}/mcp/oauth/request?state=${encodeURIComponent(state())}`);
+    expect(await res.json()).toEqual({
+      clientName: 'Claude',
+      scope: null,
+      resource: null,
+      agents: [{ path: 'Agents/mechanic.agent', name: 'delivery-mechanic', description: 'Moves code around.' }],
+    });
+  });
+
+  it('says so when the agents cannot be listed, rather than passing it off as having none', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const failing = {
+      listChoices: async () => {
+        throw new Error('checkout unavailable');
+      },
+      choosable: async () => null,
+    };
+    const { base } = await mount({ agents: failing });
+    const res = await fetch(`${base}/mcp/oauth/request?state=${encodeURIComponent(state())}`);
+    expect(await res.json()).toEqual({
+      clientName: 'Claude',
+      scope: null,
+      resource: null,
+      agents: [],
+      agentsUnavailable: true,
+    });
+  });
+});
+
+describe('Finish records the choice', () => {
+  it('Everything — no choice, null or empty — reaches the provider as null, exactly as before', async () => {
+    const { base, issueAuthCode } = await mount();
+    for (const body of [{}, { agentPath: null }, { agentPath: '' }]) {
+      const st = state();
+      const res = await finish(base, { state: st, ...body });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({ redirectTo: 'https://agent.example.com/cb?code=c1' });
+    }
+    expect(issueAuthCode).toHaveBeenCalledTimes(3);
+    for (const call of issueAuthCode.mock.calls as unknown as unknown[][]) expect(call[2]).toBeNull();
+  });
+
+  it('an agent on offer reaches the provider as its normalized path', async () => {
+    const { base, issueAuthCode } = await mount();
+    const res = await finish(base, { state: state(), agentPath: '/Agents/mechanic.agent' });
+    expect(res.status).toBe(200);
+    expect(issueAuthCode).toHaveBeenCalledWith('u1', expect.objectContaining({ c: 'client-1' }), 'Agents/mechanic.agent');
+  });
+
+  it.each([
+    ['a file the person may not read', 'Agents/secret.agent'],
+    ['a file that does not exist', 'Agents/none.agent'],
+    ['a path that is not an agent', 'notes.md'],
+    ['a value that is not a path', 42],
+  ])('refuses %s with one answer, minting nothing', async (_what, agentPath) => {
+    const { base, issueAuthCode } = await mount();
+    const res = await finish(base, { state: state(), agentPath });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({ error: NOT_AN_AGENT_CHOICE });
+    expect(issueAuthCode).not.toHaveBeenCalled();
+  });
+
+  it('refuses a choice on an account linked through the GitHub facade, which has no connection to record it on', async () => {
+    const { base, completeConsent } = await mount();
+    const res = await finish(base, { state: state({ gh: true, cc: undefined }), agentPath: 'Agents/mechanic.agent' });
+    expect(res.status).toBe(400);
+    expect(completeConsent).not.toHaveBeenCalled();
+  });
+});