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

package/src/modules/kb-sync/__tests__/kb-sync.service.test.ts

@@ -22,10 +22,32 @@ function updated(branch: string): BranchSyncOutcome {
 }
 
 describe('KbSyncService', () => {
+  it('answers the sync without waiting for the tidy-up after it', async () => {
+    let finish = (): void => undefined;
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      // A tidy-up that never ends unless told to — and one that fails.
+      tidyAfterSweep: vi
+        .fn()
+        .mockImplementationOnce(
+          () => new Promise((resolve) => (finish = () => resolve({ closedEmpty: 0, removedLeftovers: 0 }))),
+        )
+        .mockRejectedValueOnce(new Error('boom')),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main']));
+    await expect(svc.sync({ branches: 'all' })).resolves.toMatchObject({ status: 'synced' });
+    expect(workflow.tidyAfterSweep).toHaveBeenCalledTimes(1);
+    await expect(svc.sync({ branches: 'all' })).resolves.toMatchObject({ status: 'synced' });
+    finish();
+  });
+
   it('syncs every known clone for an "all" request and reports unknown branches as not cloned', async () => {
     const workflow: SyncWorkflowPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
@@ -34,6 +56,8 @@ describe('KbSyncService', () => {
     expect(all.status).toBe('synced');
     expect(all.results.map((r) => r.branch)).toEqual(['main', 'ali/x']);
     expect(all.changeRequests.closedDeletedBranch).toBe(1);
+    // Every sweep for deleted branches is followed by the leftover cleanup.
+    expect(workflow.tidyAfterSweep).toHaveBeenCalledTimes(1);
     expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledWith('ali%2Fx');
 
     const some = await svc.sync({ branches: ['ali/x', 'juan/other'] });
@@ -48,6 +72,7 @@ describe('KbSyncService', () => {
           : updated(decodeURIComponent(id)),
       ),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
@@ -62,6 +87,7 @@ describe('KbSyncService', () => {
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => {
         throw new Error('origin down');
       }),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main']));
@@ -91,6 +117,7 @@ describe('KbSyncService', () => {
         return updated(branch);
       }),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
@@ -121,6 +148,7 @@ describe('KbSyncService', () => {
         return updated(decodeURIComponent(id));
       }),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
@@ -141,6 +169,7 @@ describe('KbSyncService.lastSync', () => {
     const workflow: SyncWorkflowPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     let clock = 1_000;
@@ -168,6 +197,7 @@ describe('KbSyncService.lastSync', () => {
         return updated(decodeURIComponent(id));
       }),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
@@ -188,6 +218,7 @@ describe('KbSyncService — a throwing branch step', () => {
         return updated(decodeURIComponent(id));
       }),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
@@ -208,6 +239,7 @@ describe('KbSyncService — clones the host no longer has, and clones that canno
         id === 'ali%2Fx' ? { branch: 'ali/x', outcome: 'remote-gone' } : updated(decodeURIComponent(id)),
       ),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['ali/x', 'main']));
@@ -222,6 +254,7 @@ describe('KbSyncService — clones the host no longer has, and clones that canno
     const workflow: SyncWorkflowPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const port: SyncWorkspacePort = {
@@ -251,6 +284,7 @@ describe('KbSyncService — a coalesced caller is judged by its own branches', (
         return updated(decodeURIComponent(id));
       }),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
@@ -278,6 +312,7 @@ describe('KbSyncService — a waiter keeps the branches it asked for', () => {
         return updated(decodeURIComponent(id));
       }),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));

package/src/modules/kb-sync/kb-sync.interface.ts

@@ -61,6 +61,8 @@ export interface SyncWorkflowPort {
   retireRemoteGoneClone(workspaceId: string): Promise<boolean>;
   /** The existing sweep; returns how many requests it closed. */
   closeChangeRequestsWithDeletedBranches(): Promise<number>;
+  /** The tidy-up after the sweep — empty open requests closed, leftover branches removed; never throws. */
+  tidyAfterSweep(): Promise<{ closedEmpty: number; removedLeftovers: number }>;
 }
 
 /**

package/src/modules/kb-sync/kb-sync.service.ts

@@ -187,6 +187,12 @@ export class KbSyncService implements IKbSyncService {
     } catch (err) {
       log.warn('deleted-branch sweep failed:', { err });
     }
+    // Then the tidy-up boot runs too: empty open requests closed, leftover
+    // branches of merged requests removed. Detached: it can take a while on a
+    // large repository, and the sync (often a webhook with a short timeout)
+    // must not wait on it. It never throws; the catch is for a mock or a
+    // future change that does.
+    void this.workflow.tidyAfterSweep().catch((err: unknown) => log.warn('post-sync tidy-up failed:', { err }));
 
     const result: SyncResult = {
       status: KbSyncService.statusOf(results),

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

@@ -70,15 +70,19 @@ function render(fragment: SQL): { sql: string; params: unknown[] } {
   return { sql: q.sql, params: q.params };
 }
 
-function makeProvider(queue: any[] = []) {
-  const { db, captured } = makeFakeDb(queue);
-  const provider = new BevelOAuthProvider({
+function providerDeps(db: Database) {
+  return {
     db,
     crypto: null,
     stateSecret: STATE_SECRET,
     publicFrontendUrl: FRONTEND,
     tokenPrefix: PREFIX,
-  });
+  };
+}
+
+function makeProvider(queue: unknown[] = []) {
+  const { db, captured } = makeFakeDb(queue);
+  const provider = new BevelOAuthProvider(providerDeps(db));
   return { provider, captured, db };
 }
 
@@ -292,9 +296,10 @@ describe('BevelOAuthProvider', () => {
     const { provider, captured, db } = makeProvider([
       [oldRow] /* revoke.returning */,
       [{ id: 'conn-1' }] /* the token's connection, still live */,
-      undefined /* the (throttled) use stamp */,
+      [] /* the (throttled) use stamp's first-use claim: stamped before */,
       undefined, undefined, /* prunes */
       undefined /* token insert */,
+      undefined /* the ordinary use stamp */,
     ]);
     const tokens = await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old', ['mcp']);
     expect(tokens.scope).toBe('mcp');
@@ -307,8 +312,10 @@ describe('BevelOAuthProvider', () => {
     expect((db as any).select).toHaveBeenCalledTimes(1);
     expect(render(captured.where[1])).toMatchObject({ params: ['conn-1'] });
     expect(render(captured.where[1]).sql).toMatch(/"agent_connections"."revoked_at" is null/);
-    // …and the use is stamped separately, off the refresh's own path.
-    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    // …and the use is stamped separately, off the refresh's own path: the
+    // first-use claim, then (stamped before) the ordinary stamp.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections, agentConnections]);
     expect(Object.keys(captured.set[1])).toEqual(['lastUsedAt']);
 
     // Widening is refused.
@@ -363,6 +370,7 @@ describe('BevelOAuthProvider', () => {
     const { provider, captured } = makeProvider([
       [row] /* select */,
       undefined /* token lastUsedAt touch */,
+      [] /* the connection's first-use claim: stamped before */,
       undefined /* connection lastUsedAt touch */,
       [row] /* a second verify a moment later */,
       undefined /* its token touch — and NO second connection touch */,
@@ -381,16 +389,65 @@ describe('BevelOAuthProvider', () => {
     // Both "last used" marks are touched: the token's row, and THIS token's
     // agent connection.
     await new Promise((r) => setTimeout(r, 0));
-    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
-    expect(captured.set.map((s) => Object.keys(s))).toEqual([['lastUsedAt'], ['lastUsedAt']]);
+    // The connection's stamp is two statements: the first-use claim (its
+    // id, and never stamped), then — stamped before — the ordinary stamp.
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections, agentConnections]);
+    expect(captured.set.map((s) => Object.keys(s))).toEqual([['lastUsedAt'], ['lastUsedAt'], ['lastUsedAt']]);
     expect(render(captured.where[1])).toMatchObject({ params: ['tok-row-1'] });
     expect(render(captured.where[2])).toMatchObject({ params: ['conn-1'] });
-    expect(render(captured.where[2]).sql).toMatch(/"agent_connections"."id" = \$1/);
+    expect(render(captured.where[2]).sql).toMatch(/"agent_connections"."id" = \$1 and "agent_connections"."last_used_at" is null/);
+    expect(render(captured.where[3])).toMatchObject({ params: ['conn-1'] });
+    expect(render(captured.where[3]).sql).toMatch(/"agent_connections"."id" = \$1/);
     // The connection's stamp is throttled: a verify a moment later touches
     // the token row again but not the connection — a minute has not passed.
     await provider.verifyAccessToken('bevel-mcp_live');
     await new Promise((r) => setTimeout(r, 0));
-    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections, oauthTokens]);
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections, agentConnections, oauthTokens]);
+  });
+
+  /**
+   * The FIRST stamp of a connection is the agent arriving — what the
+   * onboarding waits for — so the owner is told, once: the claim that took
+   * the row from never-used to now is the one that announces, and it is
+   * the only statement that run makes. A connection stamped before loses
+   * the claim, is stamped the ordinary way, and nobody is told.
+   */
+  it('announces an agent connection to its owner on its first use, and never again', async () => {
+    const row = {
+      id: 'tok-row-1', clientId: 'client-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
+      expiresAt: new Date(Date.now() + 60_000), userId: 'user-1', userEmail: 'alice@example.com',
+    };
+    const events = { emit: vi.fn() };
+    const fresh = makeProvider([
+      [row],
+      undefined /* token touch */,
+      [{ userId: 'user-1', client: 'Claude' }] /* the claim: this request took the first stamp */,
+    ]);
+    const freshProvider = new BevelOAuthProvider({ ...providerDeps(fresh.db), events });
+    await freshProvider.verifyAccessToken('bevel-mcp_live');
+    await new Promise((r) => setTimeout(r, 0));
+    expect(events.emit).toHaveBeenCalledTimes(1);
+    expect(events.emit).toHaveBeenCalledWith({
+      kind: 'agent-connected',
+      forUserId: 'user-1',
+      client: 'Claude',
+      agentKind: 'agent',
+      at: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+    });
+    // The claim WAS the stamp: no second write for the winner.
+    expect(fresh.captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+
+    const used = makeProvider([
+      [row],
+      undefined,
+      [] /* the claim lost: stamped before (or by a racing request) */,
+      undefined /* the ordinary stamp */,
+    ]);
+    const usedEvents = { emit: vi.fn() };
+    await new BevelOAuthProvider({ ...providerDeps(used.db), events: usedEvents }).verifyAccessToken('bevel-mcp_live');
+    await new Promise((r) => setTimeout(r, 0));
+    expect(usedEvents.emit).not.toHaveBeenCalled();
+    expect(used.captured.updateTargets).toEqual([oauthTokens, agentConnections, agentConnections]);
   });
 
   it('revokeToken (RFC 7009) ends the agent connection once no live token remains on it, as the owner\'s doing', async () => {

package/src/modules/mcp/__tests__/mcp-proxy-helpers.test.ts

@@ -68,15 +68,50 @@ describe('toListedTool', () => {
     ...over,
   });
 
-  it('passes a conforming tool through', () => {
+  it('passes a conforming tool through, its call example first', () => {
     const listed = toListedTool(proxied({ mcpName: 'gmail_send_email' }));
     expect(listed).toEqual({
       name: 'gmail_send_email',
-      description: 'a tool',
+      description: 'Call: m.t({})\n\na tool',
       inputSchema: { type: 'object', properties: {} },
     });
   });
 
+  it('generates the example from the tool\'s own schema, in the shape it really takes', () => {
+    const platform = toListedTool(
+      proxied({
+        utcpName: 'KNOWLEDGE_BASE.read_file',
+        mcpName: 'read_file',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            body: {
+              type: 'object',
+              properties: { branch: { type: 'string' }, path: { type: 'string' }, limit: { type: 'integer' } },
+              required: ['branch', 'path'],
+            },
+          },
+          required: ['body'],
+        } as never,
+      }),
+    )!;
+    expect(platform.description.split('\n')[0]).toBe(
+      'Call: KNOWLEDGE_BASE.read_file({ body: { branch: "...", path: "..." } })',
+    );
+    const flat = toListedTool(
+      proxied({
+        utcpName: 'NS.search',
+        mcpName: 'NS_search',
+        inputSchema: {
+          type: 'object',
+          properties: { query: { type: 'string' }, limit: { type: 'integer' } },
+          required: ['query'],
+        } as never,
+      }),
+    )!;
+    expect(flat.description.split('\n')[0]).toBe('Call: NS.search({ query: "..." })');
+  });
+
   it('drops a tool whose name is too long or has illegal chars (so it cannot blank the whole list)', () => {
     expect(toListedTool(proxied({ mcpName: 'has spaces' }))).toBeNull();
     expect(toListedTool(proxied({ mcpName: 'a'.repeat(129) }))).toBeNull();

package/src/modules/mcp/__tests__/mcp.app.e2e.test.ts

@@ -0,0 +1,200 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express, { type RequestHandler } from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { MCP_APP_MIME_TYPE, MCP_APP_UI_META_KEY } from '@bevel-software/platform-mcp-core';
+import { createMcpRoutes } from '../mcp.routes.js';
+import { McpService } from '../mcp.service.js';
+import { SpillStore } from '../../workspace/spill-store.js';
+import { createManualRoutes } from '../../tool-registry/manual.routes.js';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { toolDef } from '../../tool-helpers/tool-def.js';
+import { McpAppService, OPEN_PAGE_VIEW_URI_PREFIX } from '../../embed/mcp-app.js';
+import { OPEN_PAGE_TOOL } from '../../embed/embed.tools.js';
+
+/**
+ * The MCP App, over the REAL Streamable-HTTP transport with the official SDK
+ * client — the criterion as a host actually observes it: `tools/list` carries
+ * the view on `open_page`, `resources/list` offers it under the MCP App media
+ * type, and `resources/read` hands back the view with the framing metadata.
+ */
+
+const KEY = 'bevel_key_user_a';
+const PUBLIC = 'https://hexis.example';
+
+const bearerOf = (req: express.Request) => (req.headers.authorization ?? '').replace(/^Bearer\s+/i, '');
+const fakeAuth: RequestHandler = (req, res, next) => {
+  if (bearerOf(req) !== KEY) {
+    res.status(401).json({ error: 'unauthorized' });
+    return;
+  }
+  req.userId = 'user-A';
+  req.externalApiKeyId = 'tok-A';
+  next();
+};
+
+let httpServer: HttpServer | null = null;
+let client: Client | null = null;
+
+afterEach(async () => {
+  await client?.close().catch(() => undefined);
+  client = null;
+  if (httpServer) {
+    httpServer.closeAllConnections();
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+  }
+  httpServer = null;
+});
+
+/** The platform: the real proxy, the real routes, and `open_page` in the catalog. */
+async function connect(opts: { serveApps?: boolean } = {}) {
+  const app = express();
+  app.use(express.json());
+
+  const registry = new ToolRegistry();
+  for (const name of [OPEN_PAGE_TOOL, 'read_file']) {
+    registry.registerExternalTool(
+      toolDef({
+        name,
+        description: `the ${name} tool`,
+        path: `/api/agent/tools/${name}`,
+        inputs: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false },
+      }),
+    );
+  }
+  const toolRoutes = express.Router();
+  toolRoutes.use(createManualRoutes(registry, fakeAuth, async () => 'a@x.io'));
+  toolRoutes.post('/agent/tools/:name', (req, res) =>
+    res.json(
+      req.params.name === OPEN_PAGE_TOOL
+        ? { path: 'Data/Thing.md', content: '# Thing', embedUrl: `${PUBLIC}/embed?token=t`, appUrl: PUBLIC, branch: 'main' }
+        : { ok: true },
+    ),
+  );
+
+  httpServer = app.listen(0);
+  await new Promise<void>((r) => httpServer!.once('listening', () => r()));
+  const port = (httpServer.address() as AddressInfo).port;
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  const service = new McpService(
+    {
+      loopbackBaseUrl: baseUrl,
+      manualName: 'KNOWLEDGE_BASE',
+      spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+      publicFrontendUrl: PUBLIC,
+    },
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    // A deployment with no apps is the degraded shape: no capability, no view.
+    opts.serveApps === false ? undefined : new McpAppService({ publicFrontendUrl: PUBLIC }),
+  );
+  const stub = {} as never;
+  app.use('/api', createMcpRoutes(service, stub, fakeAuth, fakeAuth, stub, stub, stub, ''));
+  app.use('/api', toolRoutes);
+
+  client = new Client({ name: 'test-host', version: '1.0.0' });
+  await client.connect(
+    new StreamableHTTPClientTransport(new URL(`${baseUrl}/api/mcp`), {
+      requestInit: { headers: { Authorization: `Bearer ${KEY}` } },
+    }),
+  );
+  return client;
+}
+
+/** The URI the packaged view is served under — named by its content, so read off the service. */
+async function viewUri(): Promise<string> {
+  return (await new McpAppService({ publicFrontendUrl: PUBLIC }).manifest()).resources[0].uri;
+}
+
+describe('the hosted MCP endpoint serves the open_page view', () => {
+  it('lists open_page carrying UI metadata that names a ui:// resource', async () => {
+    const host = await connect();
+    const { tools } = await host.listTools();
+    const openPage = tools.find((t) => t.name === OPEN_PAGE_TOOL);
+    expect(openPage).toBeDefined();
+    expect(openPage!._meta).toEqual({ [MCP_APP_UI_META_KEY]: { resourceUri: await viewUri() } });
+    expect((await viewUri()).startsWith(OPEN_PAGE_VIEW_URI_PREFIX)).toBe(true);
+    // And only that tool: `read_file` is deliberately untouched.
+    expect(tools.find((t) => t.name === 'read_file')!._meta).toBeUndefined();
+  }, 30_000);
+
+  it('lists the view with the MCP App media type', async () => {
+    const host = await connect();
+    const { resources } = await host.listResources();
+    const uri = await viewUri();
+    const view = resources.find((r) => r.uri === uri);
+    expect(view).toBeDefined();
+    expect(view!.mimeType).toBe(MCP_APP_MIME_TYPE);
+    expect(view!._meta).toMatchObject({
+      [MCP_APP_UI_META_KEY]: { csp: { connectDomains: [PUBLIC], resourceDomains: [PUBLIC] } },
+    });
+  }, 30_000);
+
+  it('reads the view, reaching exactly the deployment own origin and asking for no sandbox domain', async () => {
+    const host = await connect();
+    const read = await host.readResource({ uri: await viewUri() });
+    expect(read.contents).toHaveLength(1);
+    const [content] = read.contents as Array<{ mimeType: string; text: string; _meta: Record<string, unknown> }>;
+    expect(content.mimeType).toBe(MCP_APP_MIME_TYPE);
+    expect(content.text).toContain('ui/initialize');
+    expect(content._meta[MCP_APP_UI_META_KEY]).toMatchObject({
+      csp: { connectDomains: [PUBLIC], resourceDomains: [PUBLIC] },
+      prefersBorder: false,
+    });
+    // No frames: a chat host's sandbox blocks them, so the view does not ask.
+    expect((content._meta[MCP_APP_UI_META_KEY] as { csp: Record<string, unknown> }).csp).not.toHaveProperty(
+      'frameDomains',
+    );
+    // The host's default sandbox: the field's format is each host's own, and
+    // a value a host rejects is a view that never renders.
+    expect(content._meta[MCP_APP_UI_META_KEY]).not.toHaveProperty('domain');
+  }, 30_000);
+
+  it('refuses a resource it does not serve, naming the ones it does', async () => {
+    const host = await connect();
+    await expect(host.readResource({ uri: 'ui://hexis/not-a-view.html' })).rejects.toThrow(
+      /No resource at ui:\/\/hexis\/not-a-view\.html/,
+    );
+  }, 30_000);
+
+  /**
+   * A deployment that serves no view must not declare the capability: a
+   * client would list resources and be told the method does not exist, which
+   * reads as a broken endpoint rather than as "this one has no apps".
+   */
+  it('declares no resources capability when the deployment serves no app', async () => {
+    const host = await connect({ serveApps: false });
+    expect(host.getServerCapabilities()?.resources).toBeUndefined();
+    const { tools } = await host.listTools();
+    // Every tool is still listed, and still carries no view.
+    expect(tools.find((t) => t.name === OPEN_PAGE_TOOL)).toBeDefined();
+    expect(tools.find((t) => t.name === OPEN_PAGE_TOOL)!._meta).toBeUndefined();
+  }, 30_000);
+
+  /**
+   * The view frames `structuredContent.embedUrl` — it has nowhere else to
+   * read it — so a tool with a view must answer structured content as well
+   * as the text the model reads. A tool without one answers text alone.
+   */
+  it('answers open_page with structured content the view can read, and read_file without', async () => {
+    const host = await connect();
+    const opened = await host.callTool({ name: OPEN_PAGE_TOOL, arguments: { path: 'Data/Thing.md' } });
+    expect(opened.structuredContent).toMatchObject({ embedUrl: `${PUBLIC}/embed?token=t`, branch: 'main' });
+    expect((opened.content as Array<{ type: string; text: string }>)[0].text).toContain('embedUrl');
+    const read = await host.callTool({ name: 'read_file', arguments: { path: 'Data/Thing.md' } });
+    expect(read.structuredContent).toBeUndefined();
+  }, 30_000);
+
+  it('declares the resources capability when it does', async () => {
+    const host = await connect();
+    expect(host.getServerCapabilities()?.resources).toBeDefined();
+  }, 30_000);
+});

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

@@ -1296,9 +1296,11 @@ describe('a connected tool whose schema is invalid is not offered to agents', ()
     // The same chain, same namespace, on the sibling: bound and callable. This
     // is what makes the line above a statement about the HIDDEN tool rather
     // than about a namespace the chain could not reach at all.
+    // Called the way its `Call:` line shows: a connected tool takes its
+    // arguments flat, and the same call wrapped in `body` is refused.
     const sibling = await client.callTool({
       name: 'call_tool_chain',
-      arguments: { code: 'return notion.srv_fine({ body: {} });' },
+      arguments: { code: 'return notion.srv_fine({});' },
     });
     expect(sibling.isError).toBeFalsy();
   });

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

@@ -14,7 +14,7 @@ import { toolDef } from '../../tool-helpers/tool-def.js';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { TOOL_PREFIX_LINE, platformInstructions } from '../../agent-instructions/index.js';
 import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
-import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { splitCallLine } from '@bevel-software/platform-mcp-core';
 import type { AgentEventInput, IAgentEventRecorder } from '../../audit/audit.contract.js';
 
 /** The platform-owned part of the handshake text: the header plus the shared file rules. */
@@ -279,7 +279,9 @@ describe('McpService (UTCP→MCP proxy)', () => {
     const { tools } = await client.listTools();
     for (const name of ['call_tool_chain', 'list_tools', 'tools_info']) {
       const served = tools.find((t) => t.name === name)!;
-      expect(served.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `), name).toBe(true);
+      // Behind its `Call:` line, the first line of every description.
+      expect(served.description!.startsWith(`Call: ${name}(`), name).toBe(true);
+      expect(splitCallLine(served.description!).rest.startsWith(`${GUIDE_FIRST_SENTENCE} `), name).toBe(true);
       expect(served.description!.split(GUIDE_FIRST_SENTENCE), name).toHaveLength(2);
     }
     const chain = tools.find((t) => t.name === 'call_tool_chain')!;
@@ -614,33 +616,40 @@ describe('McpService — agent instructions', () => {
       expect.stringContaining('mcp-description.md'),
       expect.objectContaining({ message: 'disk' }),
     );
-    // And the four tools carry the fixed line alone, ahead of the guide-first
+    // And the four tools carry the fixed line alone — behind the call line,
+    // which stays first whatever is prepended, and ahead of the guide-first
     // opening every listed tool has.
     const { tools } = await client.listTools();
     for (const name of KB_TOOLS) {
       expect(tools.find((t) => t.name === name)?.description).toBe(
-        `${TOOL_PREFIX_LINE}\n\n${GUIDE_FIRST_SENTENCE} original ${name} description`,
+        `Call: KNOWLEDGE_BASE.${name}({})\n\n${TOOL_PREFIX_LINE}\n\n${GUIDE_FIRST_SENTENCE} original ${name} description`,
       );
     }
   });
 
-  it('prefixes exactly the four knowledge-base tools; every other description is as the catalog lists it', async () => {
+  it('prefixes exactly the four knowledge-base tools; every other description gains only its call line and the guide-first opening', async () => {
     const client = await setup({ readAgentPreamble: async () => 'Acme builds solar farms.', extraTools: KB_TOOLS });
     const { tools } = await client.listTools();
     const byName = Object.fromEntries(tools.map((t) => [t.name, t.description]));
     const prefix = `${TOOL_PREFIX_LINE} Acme builds solar farms.`;
     for (const name of KB_TOOLS) {
-      expect(byName[name], name).toBe(`${prefix}\n\n${GUIDE_FIRST_SENTENCE} original ${name} description`);
+      expect(byName[name], name).toBe(
+        `Call: KNOWLEDGE_BASE.${name}({})\n\n${prefix}\n\n${GUIDE_FIRST_SENTENCE} original ${name} description`,
+      );
     }
     // Regression: the rest carries only what the catalog gives every tool —
-    // the guide-first opening — and never the purpose prefix; the meta-tools
-    // open with that sentence too.
-    expect(byName.ask).toBe(`${GUIDE_FIRST_SENTENCE} echo the prompt`);
-    expect(byName.boom).toBe(`${GUIDE_FIRST_SENTENCE} always errors`);
-    expect(byName.refy).toBe(`${GUIDE_FIRST_SENTENCE} has $defs/$ref in its schema`);
+    // its own call line, then the guide-first opening — and never the purpose
+    // prefix; the meta-tools open the same way.
+    expect(byName.ask).toBe(`Call: KNOWLEDGE_BASE.ask({ body: { prompt: "..." } })\n\n${GUIDE_FIRST_SENTENCE} echo the prompt`);
+    expect(byName.boom).toBe(`Call: KNOWLEDGE_BASE.boom({})\n\n${GUIDE_FIRST_SENTENCE} always errors`);
+    // Its `to` is an array of a `$ref`'d shape: the example takes the type at
+    // the top and says nothing about what is inside — the interface does that.
+    expect(byName.refy).toBe(
+      `Call: KNOWLEDGE_BASE.refy({ body: { to: [] } })\n\n${GUIDE_FIRST_SENTENCE} has $defs/$ref in its schema`,
+    );
     for (const meta of ['call_tool_chain', 'list_tools', 'tools_info']) {
       expect(byName[meta], meta).not.toContain(TOOL_PREFIX_LINE);
-      expect(byName[meta]!.startsWith(`${GUIDE_FIRST_SENTENCE} `), meta).toBe(true);
+      expect(splitCallLine(byName[meta]!).rest.startsWith(`${GUIDE_FIRST_SENTENCE} `), meta).toBe(true);
     }
   });
 
@@ -658,7 +667,8 @@ describe('McpService — agent instructions', () => {
     });
     const { tools } = await client.listTools();
     for (const name of KB_TOOLS) {
-      expect(tools.find((t) => t.name === name)?.description.startsWith(`${TOOL_PREFIX_LINE} Acme.`)).toBe(true);
+      expect(tools.find((t) => t.name === name)?.description).toContain(`\n\n${TOOL_PREFIX_LINE} Acme.`);
+      expect(tools.find((t) => t.name === name)?.description.startsWith('Call: ')).toBe(true);
     }
   });
 });