@bevel-software/platform-core-backend 0.35.0 → 0.37.0

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

@@ -2,13 +2,13 @@ import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('sync');
-import { sanitizeError } from '../workflow/index.js';
+import { sanitizeError } from '../version-control/index.js';
 import type {
   IKbSyncService,
   LastSync,
   SyncRequest,
   SyncResult,
-  SyncWorkflowPort,
+  SyncVersionControlPort,
   SyncWorkspacePort,
 } from './kb-sync.interface.js';
 
@@ -44,7 +44,7 @@ export class KbSyncService implements IKbSyncService {
   private last: LastSync | null = null;
 
   constructor(
-    private readonly workflow: SyncWorkflowPort,
+    private readonly versionControl: SyncVersionControlPort,
     private readonly workspaces: SyncWorkspacePort,
     private readonly now: () => number = () => Date.now(),
   ) {}
@@ -152,9 +152,9 @@ export class KbSyncService implements IKbSyncService {
       }
       let outcome: BranchSyncOutcome;
       try {
-        outcome = await this.workflow.syncWorkspaceFromRemote(id);
+        outcome = await this.versionControl.syncWorkspaceFromRemote(id);
       } catch (err) {
-        // The workflow step promises outcomes, not throws — but one broken
+        // The version-control sync step promises outcomes, not throws — but one broken
         // clone must never take the other branches, the sweep, or every
         // coalesced caller down with it, so the promise is enforced here too.
         const message = sanitizeError(err);
@@ -165,11 +165,11 @@ export class KbSyncService implements IKbSyncService {
       if (outcome.outcome === 'remote-gone') {
         // The host deleted the branch. Left in place, the stale clone would
         // fail its fetch on every following full sync — and a webhook host
-        // disables a subscription that keeps failing. The workflow retires it
+        // disables a subscription that keeps failing. The version-control service retires it
         // under the branch-lifecycle lock, after asking origin again, so a
         // branch recreated since the pull keeps its clone. Best-effort.
         try {
-          const removed = await this.workflow.retireRemoteGoneClone(id);
+          const removed = await this.versionControl.retireRemoteGoneClone(id);
           if (removed) log.info(`removed the clone of "${branch}" — deleted on the host`);
           else log.info(`kept the clone of "${branch}" — it is back on the host, or already gone`);
         } catch (err) {
@@ -183,7 +183,7 @@ export class KbSyncService implements IKbSyncService {
     // pointed at it. Best-effort — it fails safe by closing nothing.
     let closedDeletedBranch = 0;
     try {
-      closedDeletedBranch = await this.workflow.closeChangeRequestsWithDeletedBranches();
+      closedDeletedBranch = await this.versionControl.closeChangeRequestsWithDeletedBranches();
     } catch (err) {
       log.warn('deleted-branch sweep failed:', { err });
     }
@@ -192,7 +192,7 @@ export class KbSyncService implements IKbSyncService {
     // 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 }));
+    void this.versionControl.tidyAfterSweep().catch((err: unknown) => log.warn('post-sync tidy-up failed:', { err }));
 
     const result: SyncResult = {
       status: KbSyncService.statusOf(results),

package/src/modules/marketplace/__tests__/github-facade.test.ts

@@ -9,7 +9,7 @@ import express from 'express';
 import type { AuthUser } from '@bevel-software/platform-shared';
 
 import { MarketplaceRepoService, type MarketplaceCompiler } from '../marketplace-repo.service.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import {
   GitHubFacadeCredentialsService,
   GitHubFacade,

package/src/modules/marketplace/__tests__/marketplace-git.test.ts

@@ -10,7 +10,7 @@ import type { AuthUser } from '@bevel-software/platform-shared';
 
 import { MarketplaceRepoService, type MarketplaceCompiler } from '../marketplace-repo.service.js';
 import { createMarketplaceGitRoutes } from '../git-http.routes.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import type { VirtualTree } from '../../plugins/compile/compile-marketplace.js';
 
 const execFileAsync = promisify(execFile);

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

@@ -6,8 +6,8 @@ import {
   flattenDiscoveredTool,
   toCallToolResult,
   toListedTool,
-} from '../mcp.service.js';
-import type { ProxiedTool } from '../mcp.service.js';
+} from '@bevel-software/platform-mcp-core';
+import type { ProxiedTool } from '@bevel-software/platform-mcp-core';
 
 function utcpTool(name: string, bodyProps: Record<string, unknown>, required: string[] = []): UtcpTool {
   return {
@@ -72,8 +72,10 @@ describe('toListedTool', () => {
     const listed = toListedTool(proxied({ mcpName: 'gmail_send_email' }));
     expect(listed).toEqual({
       name: 'gmail_send_email',
+      title: 'Gmail send email',
       description: 'Call: m.t({})\n\na tool',
       inputSchema: { type: 'object', properties: {} },
+      annotations: { readOnlyHint: false },
     });
   });
 

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

@@ -12,16 +12,15 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 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 { SpillStore } from '../../workspace/index.js';
+import { ToolRegistry, createManualRoutes } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { platformInstructions } from '../../agent-instructions/index.js';
 import { startFakeDownstreamMcpServer, type FakeDownstreamMcpServer } from './fake-downstream-mcp-server.js';
-import { registerBevelSecretsVariableLoader } from '../../secrets-vault/secrets-variable-loader.js';
-import type { ForcedRefreshOutcome, ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
-import type { IToolManualService } from '../../tool-manuals/tool-manuals.contract.js';
+import { registerBevelSecretsVariableLoader } from '../../secrets-vault/index.js';
+import type { ForcedRefreshOutcome, ISecretsVaultService } from '../../secrets-vault/index.js';
+import type { IToolManualService } from '../../tool-manuals/index.js';
 import { setLogger } from '../../../shared/logging.js';
 import type { ILogger } from '../../../shared/logger.contract.js';
 import { formatProbeReport, probeFirstCall } from '../first-call-probe.js';
@@ -117,6 +116,8 @@ interface PlatformOptions {
   /** Bind this port — how a "restarted" platform comes back at the same address. */
   port?: number;
   readAgentPreamble?: () => Promise<string | null>;
+  /** The default branch the instructions name, read per request as the composition root wires it. */
+  defaultBranch?: () => string;
   /** Extra manuals the catalog serves each caller (beyond the KB manual). */
   manualsFor?: (bearer: string) => unknown[];
   poolNow?: () => number;
@@ -185,6 +186,7 @@ async function startPlatform(opts: PlatformOptions = {}): Promise<Platform> {
     spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
     publicFrontendUrl: 'http://localhost:5173',
     readAgentPreamble: opts.readAgentPreamble,
+    defaultBranch: opts.defaultBranch,
     downstreamPool: opts.poolNow ? { now: opts.poolNow } : undefined,
   }, opts.secretsVault, opts.toolManuals);
   const stub = {} as never;
@@ -487,11 +489,28 @@ describe('agent instructions over the real transport', () => {
   it('the initialize result carries the platform text and the preamble body inline', async () => {
     const { baseUrl } = await startPlatform({
       readAgentPreamble: async () => 'Acme builds solar farms.\n\n<!-- private -->Look in Projects/ first.',
+      defaultBranch: () => 'target-company-state',
     });
     const { client } = await connectSdkClient(baseUrl);
     const instructions = client.getInstructions();
-    expect(instructions).toBe(`${platformInstructions(DEFAULT_KB_LAYOUT)}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`);
+    expect(instructions).toBe(
+      `${platformInstructions(DEFAULT_KB_LAYOUT, 'target-company-state')}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`,
+    );
     expect(instructions).not.toContain('private');
+    // The deployment's default branch, by its own name — not `main`.
+    expect(instructions).toContain("This knowledge base's default branch is `target-company-state`");
+  });
+
+  it('a default branch renamed between two initializes is the one the second names', async () => {
+    let branch = 'target-company-state';
+    const { baseUrl } = await startPlatform({ defaultBranch: () => branch });
+    const { client: before } = await connectSdkClient(baseUrl);
+    branch = 'company-state';
+    const { client: after } = await connectSdkClient(baseUrl);
+    expect(after.getInstructions()).toContain("This knowledge base's default branch is `company-state`");
+    expect(after.getInstructions()).not.toContain('target-company-state');
+    // Nothing else moved: the text is the old one with the name swapped.
+    expect(after.getInstructions()).toBe(before.getInstructions()!.replaceAll('target-company-state', 'company-state'));
   });
 
   it('a later initialize on the SAME process after the file changed carries the new text — read per request', async () => {
@@ -651,6 +670,7 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     } as unknown as ISecretsVaultService;
     registerBevelSecretsVariableLoader(vault);
     const toolManuals = {
+      sharedSignInKeysForManual: async () => [],
       userScopedKeysForManual: async (manual: string) =>
         manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion sign-in', oauth: true }] : [],
     } as unknown as IToolManualService;
@@ -770,6 +790,45 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     expect(refreshLines(logs)[0]).toContain('manual=\\"notion\\" user=\\"user-A\\" outcome=rejected');
   });
 
+  it('a WORKSPACE connection rejected on refresh tells the caller a tool owner has to reconnect it, and does not retry', async () => {
+    quiet();
+    let valid = 'token-1';
+    downstream = await startFakeDownstreamMcpServer({ acceptsToken: (t) => t === valid });
+    // The same sign-in, declared as one shared connection: the manual reports
+    // it under `sharedSignInKeysForManual`, the vault under the owner's row.
+    const state = { token: 'token-1' as string | null, refreshes: 0 };
+    const vault = {
+      resolve: async (_userId: string, key: string) => (key === KEY ? state.token : null),
+      statusFor: async (_userId: string, keys: string[]) =>
+        keys.map((key) => ({ key, adminConfigured: true, adminKind: 'oauth', userConfigured: false, adminAuthorized: state.token !== null })),
+      forceRefresh: async (_userId: string, key: string) => {
+        expect(key).toBe(KEY);
+        state.refreshes += 1;
+        state.token = null;
+        return 'rejected' as const;
+      },
+    } as unknown as ISecretsVaultService;
+    registerBevelSecretsVariableLoader(vault);
+    const toolManuals = {
+      sharedSignInKeysForManual: async (manual: string) =>
+        manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion sign-in' }] : [],
+      userScopedKeysForManual: async () => [],
+    } as unknown as IToolManualService;
+    const { baseUrl } = await startPlatform({ manualsFor: notionManual(downstream), secretsVault: vault, toolManuals });
+    const { client } = await connectSdkClient(baseUrl);
+    await client.callTool({ name: 'notion_srv_echo', arguments: { text: 'one' } });
+
+    valid = 'nothing-valid-any-more';
+
+    const res = await client.callTool({ name: 'notion_srv_echo', arguments: { text: 'two' } });
+    expect(res.isError).toBe(true);
+    expect(toolText(res)).toContain('The workspace connection for "notion" was rejected by the provider and has been disconnected');
+    expect(toolText(res)).toContain('A tool owner has to reconnect it on http://localhost:5173/connect');
+    expect(toolText(res)).not.toContain('Your sign-in');
+    expect(state.refreshes).toBe(1);
+    expect(downstream.executions()).toBe(1); // nothing was retried against a dead workspace grant
+  });
+
   it('transient refresh failure: the original error comes back, the token is kept, and a later call tries again', async () => {
     quiet();
     let now = 1_000_000;
@@ -940,6 +999,7 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     const { state, vault } = fakeSignIn('token-1', () => 'refreshed');
     const boom = new Error('catalog read failed\u009b31m\nerror: forged by the manual name\u2028tail');
     const toolManuals = {
+      sharedSignInKeysForManual: async () => [],
       userScopedKeysForManual: async (manual: string) => {
         if (broken) throw boom;
         return manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion sign-in', oauth: true }] : [];
@@ -1061,6 +1121,7 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     } as unknown as ISecretsVaultService;
     registerBevelSecretsVariableLoader(withKind);
     const toolManuals = {
+      sharedSignInKeysForManual: async () => [],
       userScopedKeysForManual: async (manual: string) =>
         manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion key', oauth: false }] : [],
     } as unknown as IToolManualService;

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

@@ -7,18 +7,16 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { CallTemplate } from '@utcp/sdk';
 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 { SpillStore } from '../../workspace/index.js';
+import { createManualRoutes, ToolRegistry, GUIDE_FIRST_SENTENCE } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
+import type { AgentEventInput, IAgentEventRecorder } from '../../audit/index.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 { 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. */
-const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT, '');
 
 /**
  * End-to-end proxy test: a real express app serving the registry-driven tool
@@ -56,6 +54,10 @@ async function setup(deps?: {
   auditRecorder?: IAgentEventRecorder;
   /** The agent connection an OAuth caller arrived through (with `tokenId: null`). */
   connectionId?: string | null;
+  /** The agent the credential connects as; absent = Everything. */
+  agentPath?: string | null;
+  /** Released skills listed beside `rfi` — listed only: `get_skill` answers not-found for them. */
+  listedOnly?: { name: string; description: string; path: string }[];
 }) {
   skillRequests = [];
   const registry = new ToolRegistry();
@@ -117,7 +119,7 @@ async function setup(deps?: {
   app.post('/api/agent/tools/list_skills', (req, res) => {
     const b = (req.body ?? {}) as Record<string, unknown>;
     skillRequests.push({ tool: 'list_skills', body: b });
-    const released = [{ name: 'rfi', description: 'RFI answers', path: 'Plugins/Sales/rfi' }];
+    const released = [{ name: 'rfi', description: 'RFI answers', path: 'Plugins/Sales/rfi' }, ...(deps?.listedOnly ?? [])];
     res.json({
       skills:
         typeof b.branch === 'string'
@@ -194,6 +196,10 @@ async function setup(deps?: {
   httpServer = await new Promise<HttpServer>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });
+  // Every server a test opens is closed after it, not only the last: a test
+  // that sets up twice would otherwise leave the first one listening.
+  const opened = httpServer;
+  cleanups.push(() => new Promise<void>((r) => opened.close(() => r())));
   const port = (httpServer.address() as { port: number }).port;
   loopbackBase = `http://127.0.0.1:${port}`;
 
@@ -215,7 +221,7 @@ async function setup(deps?: {
   );
   lastService = mcp;
   const tokenId = deps?.tokenId === undefined ? 'tok-1' : deps.tokenId;
-  return connectClient(mcp, tokenId, deps?.connectionId ?? null);
+  return connectClient(mcp, tokenId, deps?.connectionId ?? null, deps?.agentPath ?? null);
 }
 
 /** The service `setup` built last — for a test that needs a SECOND request against the same service. */
@@ -228,9 +234,14 @@ let lastService: McpService | undefined;
  * The initialize message is passed so the server carries instructions,
  * exactly as the route's initialize request would.
  */
-async function connectClient(mcp: McpService, tokenId: string | null, connectionId: string | null = null): Promise<Client> {
+async function connectClient(
+  mcp: McpService,
+  tokenId: string | null,
+  connectionId: string | null = null,
+  agentPath: string | null = null,
+): Promise<Client> {
   const server = await mcp.createRequestServer(
-    { userId: 'user-A', tokenId, connectionId, bearer: 'bevel_testkey' },
+    { userId: 'user-A', tokenId, connectionId, agentPath, bearer: 'bevel_testkey' },
     { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test-client', version: '0.0.0' } } },
   );
 
@@ -356,12 +367,14 @@ describe('McpService — per-user credential pre-check', () => {
       keys.map((key) => ({ key, adminConfigured: false, userConfigured, userAuthorized, grantedScopes })),
   });
   const manualsWithUserVar = {
+    sharedSignInKeysForManual: async () => [],
     userScopedKeysForManual: async (manual: string) =>
       manual === 'KNOWLEDGE_BASE'
         ? [{ key: 'KNOWLEDGE_BASE_API_KEY', name: 'API_KEY', label: 'Your API key', oauth: false }]
         : [],
   };
   const manualsWithOAuthVar = {
+    sharedSignInKeysForManual: async () => [],
     userScopedKeysForManual: async (manual: string) =>
       manual === 'KNOWLEDGE_BASE'
         ? [{ key: 'KNOWLEDGE_BASE_GOOGLE', name: 'GOOGLE', label: 'Google', oauth: true }]
@@ -369,6 +382,7 @@ describe('McpService — per-user credential pre-check', () => {
   };
   // An OAuth var that requires two scopes — for the scope-coverage cases.
   const manualsWithScopedOAuthVar = {
+    sharedSignInKeysForManual: async () => [],
     userScopedKeysForManual: async (manual: string) =>
       manual === 'KNOWLEDGE_BASE'
         ? [
@@ -383,9 +397,46 @@ describe('McpService — per-user credential pre-check', () => {
         : [],
   };
   const manualsNoUserVar = {
+    sharedSignInKeysForManual: async () => [],
     userScopedKeysForManual: async () =>
       [] as { key: string; name: string; label: string | null; oauth: boolean }[],
   };
+  // A WORKSPACE connection (a managed connector an owner connects once for
+  // everyone): no personal variable, one shared sign-in.
+  const manualsWithSharedSignIn = {
+    sharedSignInKeysForManual: async (manual: string) =>
+      manual === 'KNOWLEDGE_BASE'
+        ? [{ key: 'KNOWLEDGE_BASE_ACCESS_TOKEN', name: 'ACCESS_TOKEN', label: 'HubSpot sign-in', oauthScopes: ['crm.objects.contacts.read'] }]
+        : [],
+    userScopedKeysForManual: async () => [] as { key: string; name: string; label: string | null; oauth: boolean }[],
+  };
+  const sharedVault = (adminAuthorized: boolean, adminGrantedScopes?: string) => ({
+    statusFor: async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, adminConfigured: adminAuthorized, userConfigured: false, adminAuthorized, adminGrantedScopes })),
+  });
+
+  describe('a workspace connection nobody has made', () => {
+    it('refuses the call with words that say an owner connects it, without resetting the caller’s own grant', async () => {
+      const revokeOAuthAccess = vi.fn(async () => undefined);
+      const client = await setup({ secretsVault: sharedVault(false), toolManuals: manualsWithSharedSignIn, tokenId: null, revokeOAuthAccess });
+      const res = await client.callTool({ name: 'ask', arguments: { body: { prompt: 'hello' } } });
+      expect(res.isError).toBe(true);
+      const text = (res.content as Array<{ text: string }>)[0].text;
+      expect(text).toMatch(/HubSpot sign-in \(a tool owner connects this for the workspace\)/);
+      expect(text).toMatch(/\/connect/);
+      expect(revokeOAuthAccess).not.toHaveBeenCalled();
+    });
+
+    it('is hidden from a connection-key listing until an owner connects it with a covering token', async () => {
+      const names = async (c: Awaited<ReturnType<typeof setup>>) => (await c.listTools()).tools.map((t) => t.name).sort();
+      const unconnected = await setup({ secretsVault: sharedVault(false), toolManuals: manualsWithSharedSignIn });
+      expect(await names(unconnected)).toEqual(['call_tool_chain', 'list_tools', 'tools_info']);
+      const underScoped = await setup({ secretsVault: sharedVault(true, 'oauth'), toolManuals: manualsWithSharedSignIn });
+      expect(await names(underScoped)).toEqual(['call_tool_chain', 'list_tools', 'tools_info']);
+      const connected = await setup({ secretsVault: sharedVault(true, 'oauth crm.objects.contacts.read'), toolManuals: manualsWithSharedSignIn });
+      expect(await names(connected)).toEqual(['ask', 'boom', 'call_tool_chain', 'list_tools', 'refy', 'tools_info']);
+    });
+  });
 
   it('gates a tool whose personal credential is unset — returns the setup link, not the tool', async () => {
     const client = await setup({ secretsVault: vault(false), toolManuals: manualsWithUserVar });
@@ -657,7 +708,7 @@ describe('McpService — agent instructions', () => {
     // The listing filter registers only ready tools; the fake manual catalog
     // says every tool is ready, so the four survive it and carry the prefix.
     const vault = { statusFor: async (_u: string, keys: string[]) => keys.map((key) => ({ key, userConfigured: true })) };
-    const manuals = { userScopedKeysForManual: async () => [{ key: 'KNOWLEDGE_BASE_X', name: 'X', oauth: false }] };
+    const manuals = { sharedSignInKeysForManual: async () => [], userScopedKeysForManual: async () => [{ key: 'KNOWLEDGE_BASE_X', name: 'X', oauth: false }] };
     const client = await setup({
       readAgentPreamble: async () => 'Acme.',
       extraTools: KB_TOOLS,
@@ -886,7 +937,7 @@ describe('McpService — the Audit log records what an agent calls', () => {
   it('serves prompts from the default branch only, never a draft', async () => {
     const client = await setup();
     const { prompts } = await client.listPrompts();
-    expect(prompts.map((p) => p.name)).toEqual(['rfi']);
+    expect(prompts.map((p) => p.name)).toEqual(['onboard', 'rfi']);
 
     const got = await client.getPrompt({ name: 'rfi' });
     const text = got.messages[0].content.text as string;
@@ -899,10 +950,37 @@ describe('McpService — the Audit log records what an agent calls', () => {
     expect(skillRequests.every((r) => r.body.branch === undefined)).toBe(true);
   });
 
+  it('offers the platform onboard prompt, pointing at the guide section, while no skill takes its name', async () => {
+    const client = await setup();
+    const got = await client.getPrompt({ name: 'onboard' });
+    expect(got.messages[0].content.text).toContain('get_agent_guide({ body: { section: "onboarding" } })');
+  });
+
+  it("serves a workspace's own onboard skill in the platform prompt's place, and never the platform text when reading it fails", async () => {
+    const client = await setup({ listedOnly: [{ name: 'onboard', description: 'Our own onboarding', path: 'Plugins/People/onboard' }] });
+    const { prompts } = await client.listPrompts();
+    // The workspace's skill, in the catalog's own order; the platform's prompt is not added beside it.
+    expect(prompts.map((p) => [p.name, p.description])).toEqual([
+      ['rfi', 'RFI answers'],
+      ['onboard', 'Our own onboarding'],
+    ]);
+    // The skill is listed but its read answers not-found (the harness knows
+    // only `rfi`): the same failed read any prompt gets, never the platform's
+    // onboarding text under the workspace's name.
+    await expect(client.getPrompt({ name: 'onboard' })).rejects.toThrow(/Unknown skill "onboard"/);
+  });
+
+  it('serves a connection narrowed to an agent its skills and nothing beside them', async () => {
+    const client = await setup({ agentPath: 'Agents/support.agent' });
+    expect((await client.listPrompts()).prompts.map((p) => p.name)).toEqual(['rfi']);
+    await expect(client.getPrompt({ name: 'onboard' })).rejects.toThrow(/Unknown skill "onboard"/);
+  });
+
   it('records a call refused for a missing sign-in as denied, without running the tool', async () => {
     const recorder = spyRecorder();
     const vault = { statusFor: async (_u: string, keys: string[]) => keys.map((key) => ({ key, adminConfigured: false, userConfigured: false })) };
     const manuals = {
+      sharedSignInKeysForManual: async () => [],
       userScopedKeysForManual: async (manual: string) =>
         manual === 'KNOWLEDGE_BASE' ? [{ key: 'KNOWLEDGE_BASE_API_KEY', name: 'API_KEY', label: 'Your API key', oauth: false }] : [],
     };

package/src/modules/mcp/__tests__/read-only-hint.pg.test.ts

@@ -0,0 +1,194 @@
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { cp, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomBytes } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { createCoreServices, createCoreServer, stopCore, defaultKbTemplateDir, defaultStarterPacksDir, type TenantConfig } from '../../../index.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, scratchDatabaseUrl, dropScratchDatabases } from '../../../__tests__/pg-scratch.js';
+import { startFakeDownstreamMcpServer, type FakeDownstreamMcpServer } from './fake-downstream-mcp-server.js';
+
+/**
+ * A client of the public server composition, over real Streamable HTTP and a
+ * scratch Postgres. The catalog source is supplied through its public overlay
+ * hook; tool registration, manuals, hints, authentication and MCP routing are
+ * the production composition. Admin edits go through the public HTTP API too.
+ */
+const stops: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const stop of stops.splice(0).reverse()) await stop();
+}, PG_TEST_TIMEOUT);
+afterAll(dropScratchDatabases, PG_TEST_TIMEOUT);
+
+async function startPlatform(opts: { downstream?: FakeDownstreamMcpServer; catalogRevision?: boolean } = {}) {
+  const root = await mkdtemp(join(tmpdir(), 'hosted-mcp-hints-'));
+  stops.push(() => rm(root, { recursive: true, force: true }));
+  const repository = join(root, 'repository');
+  await cp(defaultKbTemplateDir(), repository, { recursive: true });
+  await writeFile(join(repository, 'roles.yaml'), 'roles:\n  Admin:\n    - admin@example.com\n');
+  const git = (args: string[]) => promisify(execFile)('git', args, { cwd: repository });
+  await git(['init', '-q', '-b', 'main']);
+  await git(['add', '.']);
+  await git(['-c', 'user.name=Test', '-c', 'user.email=admin@example.com', 'commit', '-qm', 'Seed test knowledge base']);
+  // Bind before constructing the graph so its loopback URL has the real port.
+  const server = createServer();
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  stops.push(async () => {
+    server.closeAllConnections();
+    await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  });
+  const port = (server.address() as AddressInfo).port;
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const config: TenantConfig = {
+    port, databaseUrl: await scratchDatabaseUrl('hexis_mcp_hints'), dbSchema: 'public', nodeEnv: 'test',
+    tenantId: 'bevel', externalApiKeyPrefix: 'bevel_', internalTokenPrefix: 'bevel-internal_',
+    uploadTokenPrefix: 'bevel-upload_', mcpOAuthTokenPrefix: 'bevel-mcp_',
+    workspacesRoot: join(root, 'workspaces'), backupsRoot: join(root, 'backups'),
+    spillRoot: join(root, 'spills'), agentUploadsRoot: join(root, 'uploads'), docExtractCacheRoot: join(root, 'extracts'),
+    jwtSecret: 'hosted-hints-test-secret', adminEmail: 'admin@example.com', adminPassword: 'test-password',
+    oidcIssuerUrl: '', oidcClientId: '', oidcClientSecret: '', oidcScopes: 'openid', oidcProviderLabel: 'SSO',
+    kbRepoUrl: repository, kbDirName: 'knowledge-base', gitUsername: '', gitToken: '',
+    kbTemplateDir: defaultKbTemplateDir(), starterPacksDir: defaultStarterPacksDir(),
+    updateCheckEnabled: false, loginPasswordEnabled: true, allowedEmailDomains: [],
+    secretsEncKey: randomBytes(32).toString('base64'), internalTokenSecret: 'hosted-hints-internal-secret',
+    embedSharedSecret: '', trustProxy: '', gitTimeoutMs: 30_000,
+    publicBackendUrl: baseUrl, publicFrontendUrl: baseUrl, configuredPublicFrontendUrl: baseUrl,
+    settingsEnv: { KB_REPO_URL: repository, DEFAULT_BRANCH: 'main', PROTECTED_BRANCHES: 'main' },
+  };
+  const core = await createCoreServices(config, { mirrorSharedBindings: false });
+  stops.push(() => stopCore(core));
+  const app = await createCoreServer(core, {
+    preAuth(app) {
+      app.get('/api/agent/all-tools', core.manualAuthMiddleware, (_req, res) => {
+        res.json({ manuals: [
+          { name: 'KNOWLEDGE_BASE', call_template_type: 'http', http_method: 'GET',
+            url: '${API_URL}/api/agent/utcp', content_type: 'application/json',
+            headers: { Authorization: 'Bearer ${CONNECTION_KEY}' } },
+          ...(opts.downstream ? [{ name: 'notion', call_template_type: 'mcp',
+            config: { mcpServers: { srv: { transport: 'http', url: opts.downstream.url } } } }] : []),
+        ] });
+      });
+      app.get('/api/agent/catalog-revision', core.manualAuthMiddleware, (_req, res) => {
+        if (opts.catalogRevision) res.json({ revision: 'unchanged-catalog' });
+        else res.sendStatus(404);
+      });
+    },
+  }, { boot: false });
+  server.on('request', app);
+  const login = await fetch(`${baseUrl}/api/auth/login`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email: config.adminEmail, password: config.adminPassword }),
+  });
+  expect(login.status).toBe(200);
+  const { token, user } = await login.json() as { token: string; user: { id: string } };
+  const { plaintext: key } = await core.externalApiKeyService.mint(user.id, 'metadata-test');
+  const setHint = async (name: string, readOnly: boolean | null) => {
+    const response = await fetch(`${baseUrl}/api/tool-hints/${name}`, {
+      method: 'PUT', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ readOnly }),
+    });
+    expect(response.status).toBe(200);
+  };
+  return { baseUrl, key, setHint };
+}
+
+async function connect(baseUrl: string, key: string): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/api/mcp`), {
+    requestInit: { headers: { Authorization: `Bearer ${key}` } },
+  });
+  const client = new Client({ name: 'hint-client', version: '0.0.0' }, { capabilities: {} });
+  await client.connect(transport);
+  stops.push(() => client.close());
+  return client;
+}
+
+const annotationsOf = async (client: Client) =>
+  Object.fromEntries((await client.listTools()).tools.map((t) => [t.name, t.annotations]));
+
+describe.skipIf(!PG_ADMIN_URL)('the hosted MCP endpoint lists the read-only hint', () => {
+  it('on every platform tool and every meta-tool, and no other annotation', async () => {
+    const { baseUrl, key } = await startPlatform();
+    const tools = (await (await connect(baseUrl, key)).listTools()).tools;
+    for (const tool of tools) {
+      expect(tool.title).toEqual(expect.any(String));
+      expect(tool.title!.trim()).not.toBe('');
+      expect(tool.annotations).toEqual({ readOnlyHint: expect.any(Boolean) });
+    }
+    expect(Object.fromEntries(tools.map((t) => [t.name, t.title]))).toMatchObject({
+      list_tools: 'List tools',
+      tools_info: 'Tools info',
+      call_tool_chain: 'Call tool chain',
+      read_file: 'Read file',
+      write_file: 'Write file',
+    });
+    expect(Object.fromEntries(tools.map((t) => [t.name, t.annotations]))).toMatchObject({
+      list_tools: { readOnlyHint: true },
+      tools_info: { readOnlyHint: true },
+      call_tool_chain: { readOnlyHint: false },
+      read_file: { readOnlyHint: true },
+      write_file: { readOnlyHint: false },
+    });
+  });
+
+  it("lists an admin's change on the client's NEXT tools/list, with no reconnect, and a reset undoes it", async () => {
+    const { baseUrl, key, setHint } = await startPlatform();
+    const client = await connect(baseUrl, key);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await setHint('read_file', false);
+    await setHint('write_file', true);
+    await setHint('call_tool_chain', true);
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file', 'call_tool_chain']) await setHint(name, null);
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: false });
+  });
+
+  it("lists an admin's change and its reset on the next tools/list when the tool surface is cached", async () => {
+    const { baseUrl, key, setHint } = await startPlatform({ catalogRevision: true });
+    const client = await connect(baseUrl, key);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await setHint('read_file', false);
+    await setHint('write_file', true);
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file']) await setHint(name, null);
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+  });
+
+  it('does not keep an override in the cached surface: one set before the surface is built is undone by its reset', async () => {
+    const { baseUrl, key, setHint } = await startPlatform({ catalogRevision: true });
+    await setHint('read_file', false);
+    const client = await connect(baseUrl, key);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: false });
+
+    await setHint('read_file', null);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+  });
+
+  it('lists a tool from a plugin MCP server with conservative effects', async () => {
+    const downstream = await startFakeDownstreamMcpServer();
+    stops.push(() => downstream.stop());
+    const { baseUrl, key } = await startPlatform({ downstream });
+    const tools = (await (await connect(baseUrl, key)).listTools()).tools;
+    const proxied = tools.find((t) => t.name.endsWith('echo'));
+    expect(proxied).toBeDefined();
+    expect(proxied?.annotations).toEqual({ readOnlyHint: false });
+  });
+});