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

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 });
+  });
+});

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

@@ -42,6 +42,8 @@ import {
   retiredToolMessage,
   needsAuthorizationResult,
   skillPromptText,
+  ONBOARD_PROMPT,
+  promptsForSkills,
   toListedResource,
   toReadResourceResult,
   type McpAppManifest,
@@ -50,7 +52,7 @@ import {
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
 import type { KbLayout } from '@bevel-software/platform-shared';
-import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, scopesCovered } from '../secrets-vault/index.js';
+import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, scopesCovered, userSecretGap } from '../secrets-vault/index.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
 import type { IToolManualService } from '../tool-manuals/index.js';
 import type { SpillStore } from '../workspace/index.js';
@@ -109,12 +111,19 @@ export interface McpProxyOptions {
    */
   readAgentPreamble?: AgentPreambleReader;
   /**
-   * The layout in effect, read per request: the shared file rules name the
-   * guide by the name a deployment saved for it, and the setup save applies
-   * a layout without a restart. A GETTER, so nothing snapshots the
-   * pre-setup default. Absent, the rules name `AGENTS.md`.
+   * The layout in effect, read per request: the shared file rules spell the
+   * root folders and platform files by the names a deployment saved, and the
+   * setup save applies a layout without a restart. A GETTER, so nothing
+   * snapshots the pre-setup default. Absent, the rules use the default
+   * layout. The guide is `AGENTS.md` either way.
    */
   kbLayout?: () => KbLayout;
+  /**
+   * The default branch in effect, read per request: the shared file rules
+   * name it as the branch people read. A GETTER for the same reason as the
+   * layout. Absent, the rules name no branch.
+   */
+  defaultBranch?: () => string;
   /** Bounds of the downstream (`mcp.json`) connection pool; defaults are 4h idle / 5000 entries. */
   downstreamPool?: Pick<DownstreamPoolOptions<unknown>, 'idleTtlMs' | 'maxEntries' | 'now'>;
   /**
@@ -378,7 +387,7 @@ export class McpService {
   private readonly manualFailures = new ManualFailureMemo();
   private readonly surfaceLog = new SurfaceLogThrottle();
   // One forced token refresh per (user, manual) per minute — see downstream-token-refresh.
-  private readonly tokenRefreshes: DownstreamRefreshGuard<ForcedRefreshOutcome>;
+  private readonly tokenRefreshes: DownstreamRefreshGuard<ForcedRefreshOutcome | 'rejected-shared'>;
   /**
    * The tools each pooled manual last advertised, by manual definition. A
    * downstream can only be asked what its tools are over a connection, and a
@@ -859,17 +868,32 @@ export class McpService {
     // loopback with the caller's key — so the default-branch catalog, access
     // filtering, and progressive disclosure all live ONCE behind that REST
     // surface, never duplicated here. Neither handler needs the tool catalog.
+    // The one prompt that is not a skill is the platform's `onboard`, offered
+    // only on a connection not narrowed to an agent, and only while no skill
+    // takes its name (see `promptsForSkills`).
+    const offerOnboard = agentPath === null;
     server.setRequestHandler(ListPromptsRequestSchema, async () => {
       const skills = await this.fetchSkillList(loopbackBearer);
-      const prompts: Prompt[] = skills.map((s) => ({
-        name: s.name,
-        description: s.description,
-        arguments: [],
-      }));
+      const prompts: Prompt[] = promptsForSkills(skills, offerOnboard);
       return { prompts };
     });
 
     server.setRequestHandler(GetPromptRequestSchema, async (request): Promise<GetPromptResult> => {
+      // The platform's own prompt is served exactly when `prompts/list`
+      // offered it: the connection is not narrowed and no released skill
+      // takes the name — judged on the skill LIST, the same answer the
+      // listing used, never on a read that failed. A workspace's own
+      // `onboard` skill is then read like any other prompt, and a read that
+      // fails is a failed read, not a reason to serve the platform's text.
+      if (offerOnboard && request.params.name === ONBOARD_PROMPT.name) {
+        const released = await this.fetchSkillList(loopbackBearer);
+        if (!released.some((s) => s.name === ONBOARD_PROMPT.name)) {
+          return {
+            description: ONBOARD_PROMPT.description,
+            messages: [{ role: 'user', content: { type: 'text', text: ONBOARD_PROMPT.text } }],
+          };
+        }
+      }
       const started = performance.now();
       const skill = await this.fetchSkill(loopbackBearer, request.params.name);
       // A prompt IS a skill read — the same event `get_skill` produces.
@@ -1059,13 +1083,14 @@ export class McpService {
    */
   private async composeAgentInstructions(): Promise<ComposedAgentInstructions> {
     const layout = this.opts.kbLayout?.();
+    const defaultBranch = this.opts.defaultBranch?.();
     const read = this.opts.readAgentPreamble;
-    if (!read) return composeAgentInstructions(null, layout);
+    if (!read) return composeAgentInstructions(null, layout, defaultBranch);
     try {
-      return composeAgentInstructions(await read(), layout);
+      return composeAgentInstructions(await read(), layout, defaultBranch);
     } catch (err) {
       log.warn('could not read mcp-description.md; this request gets the platform text alone:', { err });
-      return composeAgentInstructions(null, layout);
+      return composeAgentInstructions(null, layout, defaultBranch);
     }
   }
 
@@ -1559,7 +1584,7 @@ export class McpService {
       this.downstream.evictWhere((k) => k === poolKey);
       return { retry: true };
     }
-    if (outcome === 'rejected') {
+    if (outcome === 'rejected' || outcome === 'rejected-shared') {
       // The connection was dialed with a grant that no longer exists; the
       // vault's mutation signal drops it too, this keeps the next request
       // honest whether or not that is wired.
@@ -1568,8 +1593,11 @@ export class McpService {
         retry: false,
         credentialTransient: false,
         error: new Error(
-          `Your sign-in for "${manualName}" was rejected and has been disconnected. ` +
-            `Re-authorize it on ${this.opts.publicFrontendUrl}/connect, then run the tool again.`,
+          outcome === 'rejected-shared'
+            ? `The workspace connection for "${manualName}" was rejected by the provider and has been disconnected. ` +
+              `A tool owner has to reconnect it on ${this.opts.publicFrontendUrl}/connect; then run the tool again.`
+            : `Your sign-in for "${manualName}" was rejected and has been disconnected. ` +
+              `Re-authorize it on ${this.opts.publicFrontendUrl}/connect, then run the tool again.`,
         ),
       };
     }
@@ -1596,12 +1624,21 @@ export class McpService {
   private async refreshDownstreamToken(
     userId: string,
     manualName: string,
-  ): Promise<ForcedRefreshOutcome | 'guarded' | undefined> {
+  ): Promise<ForcedRefreshOutcome | 'rejected-shared' | 'guarded' | undefined> {
     const vault = this.secretsVault;
     if (!vault || !this.toolManuals || !manualName) return undefined;
     let keys: string[];
+    let sharedKeys = new Set<string>();
     try {
-      keys = (await this.toolManuals.userScopedKeysForManual(manualName)).filter((v) => v.oauth).map((v) => v.key);
+      // Every sign-in the manual declares: the caller's own, and a workspace
+      // connection every caller resolves (the vault's forceRefresh reads the
+      // shared row for an admin-scoped key, as resolve does).
+      const [own, shared] = await Promise.all([
+        this.toolManuals.userScopedKeysForManual(manualName),
+        this.toolManuals.sharedSignInKeysForManual(manualName),
+      ]);
+      keys = [...own.filter((v) => v.oauth).map((v) => v.key), ...shared.map((v) => v.key)];
+      sharedKeys = new Set(shared.map((v) => v.key));
     } catch (err) {
       // The error's own message is caller-controlled as well (it quotes the
       // manual, and may quote a provider's reply), and a raw Error handed to
@@ -1616,12 +1653,20 @@ export class McpService {
     if (keys.length === 0) return undefined;
     const attempt = this.tokenRefreshes.run(`${userId}${POOL_KEY_SEPARATOR}${manualName}`, async () => {
       const outcomes: ForcedRefreshOutcome[] = [];
+      // A dead WORKSPACE connection is told apart from a dead personal one:
+      // the caller cannot repair it, a writer of the tool can, and the words
+      // the caller gets have to say so.
+      let rejectedShared = false;
       for (const key of keys) {
         // A vault fault is not a verdict on the grant: keep the token, try later.
-        outcomes.push(await vault.forceRefresh(userId, key).catch((): ForcedRefreshOutcome => 'transient'));
+        const result = await vault.forceRefresh(userId, key).catch((): ForcedRefreshOutcome => 'transient');
+        if (result === 'rejected' && sharedKeys.has(key)) rejectedShared = true;
+        outcomes.push(result);
       }
-      const outcome: ForcedRefreshOutcome = outcomes.includes('rejected')
-        ? 'rejected'
+      const outcome: ForcedRefreshOutcome | 'rejected-shared' = outcomes.includes('rejected')
+        ? rejectedShared
+          ? 'rejected-shared'
+          : 'rejected'
         : outcomes.includes('transient')
           ? 'transient'
           : outcomes.includes('refreshed')
@@ -1681,51 +1726,37 @@ export class McpService {
     manualName: string,
   ): Promise<{ name: string; label?: string | null; brokenSignIn: boolean }[]> {
     if (!this.secretsVault || !this.toolManuals || !manualName) return [];
-    const userVars = await this.toolManuals.userScopedKeysForManual(manualName);
-    if (userVars.length === 0) return [];
-    const status = await this.secretsVault.statusFor(
-      userId,
-      userVars.map((v) => v.key),
-    );
+    const [userVars, sharedSignIns] = await Promise.all([
+      this.toolManuals.userScopedKeysForManual(manualName),
+      this.toolManuals.sharedSignInKeysForManual(manualName),
+    ]);
+    if (userVars.length === 0 && sharedSignIns.length === 0) return [];
+    const status = await this.secretsVault.statusFor(userId, [
+      ...userVars.map((v) => v.key),
+      ...sharedSignIns.map((v) => v.key),
+    ]);
     const statusMap = new Map(status.map((s) => [s.key, s]));
     const missing: { name: string; label?: string | null; brokenSignIn: boolean }[] = [];
-    for (const v of userVars) {
+    // A WORKSPACE sign-in (a managed connector enabled as one shared
+    // connection) is nobody's personal credential, but a tool whose one
+    // connection has not been made — or no longer covers what the tool
+    // declares — fails just as opaquely at the provider. Reported like a
+    // personal one, with words that say whose job it is; never a "broken
+    // sign-in" of the caller's, since there is nothing of theirs to reset.
+    for (const v of sharedSignIns) {
       const st = statusMap.get(v.key);
-      // A sign-in the caller already HAS a row for but that isn't (or is no
-      // longer) usable: dead/wiped grant, abandoned consent, missing scopes.
-      const brokenSignIn = Boolean(v.oauth && st?.userConfigured);
-      if (!st?.userConfigured) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn }); // no row at all → needs a value / sign-in
-        continue;
-      }
-      // A row of the OTHER kind is not this credential: a `.tool` edited from
-      // an OAuth sign-in to a plain key (or back) leaves the old row behind,
-      // and serving a token where a key is declared — or a key where a
-      // sign-in is — fails opaquely at the provider. Not a broken sign-in
-      // either: nothing to reset, the user has to set the credential up as
-      // the manual now declares it.
-      const declaredKind = v.oauth ? 'oauth' : 'static';
-      if (st.userKind && st.userKind !== declaredKind) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn: false });
-        continue;
-      }
-      // An OAuth-backed var whose row exists but has no token yet is NOT ready —
-      // the user has registered but not completed sign-in. Fail closed: anything
-      // other than a confirmed `true` (including a non-oauth row → undefined)
-      // counts as not-yet-authorized.
-      if (v.oauth && st.userAuthorized !== true) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn });
-        continue;
-      }
-      // An OAuth-backed var the user signed in for, but whose token was granted
-      // fewer scopes than the tool now declares, is ALSO not ready — the call would
-      // otherwise fail opaquely at the provider. Compare the live required scopes
-      // against the token's recorded granted scopes; an under-scoped (or unknown)
-      // token needs re-authorization.
-      if (v.oauth && !scopesCovered(v.oauthScopes, st.grantedScopes)) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn });
+      const connected = st?.adminAuthorized === true && scopesCovered(v.oauthScopes, st.adminGrantedScopes);
+      if (!connected) {
+        missing.push({ name: v.name, label: `${v.label ?? v.name} (a tool owner connects this for the workspace)`, brokenSignIn: false });
       }
     }
+    for (const v of userVars) {
+      // The one readiness rule `list_tool_setup` reports from (`userSecretGap`).
+      // A sign-in the caller already HAS a row for but that isn't (or is no
+      // longer) usable is a broken sign-in: abandoned consent, missing scopes.
+      const gap = userSecretGap(v, statusMap.get(v.key));
+      if (gap) missing.push({ name: v.name, label: v.label, brokenSignIn: gap === 'unauthorized' || gap === 'under-scoped' });
+    }
     return missing;
   }