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

package/src/modules/tool-manuals/__tests__/tool-manuals.mcp-oauth.test.ts

@@ -1,17 +1,19 @@
 import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
-import { NodeFs } from '../../kb-fs/node-fs.js';
-import { KbPluginSource } from '../../plugins/discovery/kb-plugin-source.js';
+// The real disk, and the service wired over it, come from the composition-root
+// fixtures, as production wires them: this suite constructs no implementation
+// from its file, its own module's included.
+import { realDisk } from '../../../__tests__/real-disk.js';
+import { realToolManualService, type McpAuthDiscoveryPort } from '../../../__tests__/tool-manuals.js';
 
 /** The one disk, as production wires it: the service and its discovery read the same one. */
-const disk = new NodeFs();
+const disk = realDisk();
 import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import { ToolManualService, type McpAuthDiscoveryPort } from '../tool-manuals.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { IAccessControl } from '../../access/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB_DIR = 'knowledge-base';
@@ -63,9 +65,10 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
   });
 
   function svcWith(discovery: McpAuthDiscoveryPort) {
-    const svc = new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
-    svc.setMcpAuthDiscovery(discovery);
-    return svc;
+    return realToolManualService(
+      { workspaceService, accessControl: allowAll, kb: testKbContext({ kbDirName: KB_DIR }), disk },
+      discovery,
+    );
   }
 
   test('a bare mcp tool whose server demands OAuth gains the synthetic sign-in var + header', async () => {
@@ -94,8 +97,10 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
 
     // The served call template carries the header the variable loader will fill.
     const templates = await svc.toManualCallTemplates('user@example.com');
-    const notionTemplate = templates.find((t) => t.name === 'notion') as any;
-    expect(notionTemplate.config.mcpServers.notion.headers).toEqual({
+    const notionTemplate = templates.find((t) => t.name === 'notion') as
+      | { config: { mcpServers: Record<string, { headers: Record<string, string> }> } }
+      | undefined;
+    expect(notionTemplate?.config.mcpServers.notion?.headers).toEqual({
       Authorization: 'Bearer ${MCP_OAUTH}',
     });
   });
@@ -298,4 +303,185 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
     // The declaration is carried verbatim, opt-out included.
     expect(hubspot.variables?.[0].oauth).toMatchObject({ clientId: 'owner-app', pkce: false });
   });
+
+  describe('liveDeclaration — what a sign-in start reads', () => {
+    const HUBSPOT_ENDPOINTS = {
+      authorizationUrl: 'https://auth.hubspot.example/authorize',
+      tokenUrl: 'https://auth.hubspot.example/token',
+    };
+
+    test('reads the file as it is now, not the catalog the last scan cached', async () => {
+      await writeDeclaredServer({ clientId: 'client-A', ...HUBSPOT_ENDPOINTS });
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      // The catalog is scanned and cached under client A…
+      const cached = (await svc.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+      expect(cached.variables?.[0].oauth?.clientId).toBe('client-A');
+
+      // …the file is edited, and nothing invalidates the catalog.
+      await writeDeclaredServer({ clientId: 'client-B', ...HUBSPOT_ENDPOINTS, scopes: ['crm.read'] });
+      const stale = (await svc.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+      expect(stale.variables?.[0].oauth?.clientId).toBe('client-A');
+
+      const live = await svc.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN');
+      expect(live?.manual.name).toBe('hubspot');
+      expect(live?.variable?.oauth).toEqual({ clientId: 'client-B', ...HUBSPOT_ENDPOINTS, scopes: ['crm.read'] });
+    });
+
+    test('a .tool file is read afresh the same way', async () => {
+      const toolsDir = join(root, wsId, KB_DIR, 'Plugins');
+      const write = (clientId: string) =>
+        writeFile(
+          join(toolsDir, 'crm.tool'),
+          JSON.stringify({
+            name: 'crm',
+            type: 'http',
+            url: 'https://api.crm.example/openapi.json',
+            variables: [{ name: 'SIGNIN', scope: 'user', oauth: { clientId, ...HUBSPOT_ENDPOINTS } }],
+          }),
+        );
+      await write('client-A');
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      await svc.listAccessible('user@example.com');
+      await write('client-B');
+      const live = await svc.liveDeclaration('user@example.com', 'crm', 'SIGNIN');
+      expect(live?.variable?.oauth?.clientId).toBe('client-B');
+    });
+
+    test('completes a client-id-only declaration from the server metadata, or carries the discovery reason', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app' });
+      const statusFor = vi.fn(async () => ({ status: 'open' as const }));
+      const providerForDeclaredClient = vi.fn(async () => ({
+        status: 'oauth' as const,
+        provider: { ...HUBSPOT_ENDPOINTS, clientId: 'owner-app', pkce: true, resource: 'https://mcp.hubspot.example/mcp' },
+      }));
+      const live = await svcWith({ statusFor, providerForDeclaredClient }).liveDeclaration(
+        'user@example.com',
+        'hubspot',
+        'HUBSPOT_TOKEN',
+      );
+      expect(live?.variable?.oauth).toEqual({
+        clientId: 'owner-app',
+        ...HUBSPOT_ENDPOINTS,
+        resource: 'https://mcp.hubspot.example/mcp',
+      });
+      // Never a zero-config probe or registration for a declared sign-in.
+      expect(statusFor).not.toHaveBeenCalled();
+
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const stuck = await svcWith({
+        statusFor,
+        providerForDeclaredClient: async () => ({ status: 'unsupported' as const, reason: 'no authorization-server metadata' }),
+      }).liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN');
+      expect(stuck?.variable?.oauth).toEqual({ clientId: 'owner-app' });
+      expect(stuck?.manual.setup).toEqual({ kind: 'oauth-manual', reason: 'no authorization-server metadata' });
+      warn.mockRestore();
+    });
+
+    test('a .tool whose sign-in endpoint fails validation answers the parser’s reason, even while the catalog holds the valid version', async () => {
+      const toolsDir = join(root, wsId, KB_DIR, 'Plugins');
+      const write = (tokenUrl: string) =>
+        writeFile(
+          join(toolsDir, 'crm.tool'),
+          JSON.stringify({
+            name: 'crm',
+            type: 'http',
+            url: 'https://api.crm.example/openapi.json',
+            variables: [{ name: 'SIGNIN', scope: 'user', oauth: { clientId: 'c', authorizationUrl: HUBSPOT_ENDPOINTS.authorizationUrl, tokenUrl } }],
+          }),
+        );
+      await write(HUBSPOT_ENDPOINTS.tokenUrl);
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      expect((await svc.listAccessible('user@example.com')).some((m) => m.name === 'crm')).toBe(true);
+
+      await write('http://127.0.0.1/token');
+      await expect(svc.liveDeclaration('user@example.com', 'crm', 'SIGNIN')).resolves.toEqual({
+        refused: '`variables[0].oauth.tokenUrl` must use https',
+      });
+      await write('https://10.0.0.5/token');
+      await expect(svc.liveDeclaration('user@example.com', 'crm', 'SIGNIN')).resolves.toEqual({
+        refused: '`variables[0].oauth.tokenUrl` host is not allowed',
+      });
+      warn.mockRestore();
+    });
+
+    test('a plugin.json sign-in whose endpoint fails validation answers the reason too, not only a log line', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS, tokenUrl: 'http://127.0.0.1/token' });
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      const live = await svc.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN');
+      expect(live?.refused).toContain('`variables[0].oauth.tokenUrl` must use https');
+      // Located by position, never by the name the entry declared (the .tool parser's rule).
+      expect(live?.refused).not.toContain('HUBSPOT_TOKEN');
+      // The catalog's public listing is unchanged by this: the server is still left out.
+      const catalog = await svc.listAccessibleCatalog('user@example.com');
+      expect(catalog.tools.some((m) => m.name === 'hubspot')).toBe(false);
+      warn.mockRestore();
+    });
+
+    test('a refusal is read-gated like the manual it would have been', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS, tokenUrl: 'http://127.0.0.1/token' });
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const denyAll = {
+        canRead: async () => false,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
+      } as unknown as IAccessControl;
+      const locked = realToolManualService({
+        workspaceService,
+        accessControl: denyAll,
+        kb: testKbContext({ kbDirName: KB_DIR }),
+        disk,
+      });
+      await expect(locked.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN')).resolves.toBeNull();
+      warn.mockRestore();
+    });
+
+    test('a workspace that cannot be opened is an error for a sign-in start, where the catalog answers empty', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS });
+      const down = {
+        getOrCreateForBranch: async () => {
+          throw new Error('workspace unavailable');
+        },
+      } as unknown as WorkspaceService;
+      const allowAll = {
+        canRead: async () => true,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+      } as unknown as IAccessControl;
+      const svc = realToolManualService({
+        workspaceService: down,
+        accessControl: allowAll,
+        kb: testKbContext({ kbDirName: KB_DIR }),
+        disk,
+      });
+      // The catalog degrades to "nothing released" and tries again next scan…
+      await expect(svc.listAccessible('user@example.com')).resolves.toEqual([]);
+      // …but a sign-in start must not read that as "no sign-in declared".
+      await expect(svc.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN')).rejects.toThrow(
+        'workspace unavailable',
+      );
+    });
+
+    test('answers no variable when the file declares none of that name, and null for an unreadable manual', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS });
+      const statusFor = vi.fn(async () => ({ status: 'oauth' as const, provider: OAUTH_PROVIDER }));
+      const svc = svcWith({ statusFor });
+      // The zero-config variable is synthesised by the catalog, not declared in any file.
+      const bare = await svc.liveDeclaration('user@example.com', 'notion', 'MCP_OAUTH');
+      expect(bare?.manual.name).toBe('notion');
+      expect(bare?.variable).toBeUndefined();
+      expect(statusFor).not.toHaveBeenCalled();
+
+      const denyAll = {
+        canRead: async () => false,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
+      } as unknown as IAccessControl;
+      const locked = realToolManualService({
+        workspaceService,
+        accessControl: denyAll,
+        kb: testKbContext({ kbDirName: KB_DIR }),
+        disk,
+      });
+      await expect(locked.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN')).resolves.toBeNull();
+    });
+  });
 });

package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts

@@ -183,6 +183,15 @@ describe('ToolManualService', () => {
     expect(manual).toBeNull();
   });
 
+  test("does not resolve a readable inline manual outside a connection's connectors", async () => {
+    // The narrowing applies after the read gate, on the manual's own path.
+    const paths: string[] = [];
+    const within = (p: string) => (paths.push(p), false);
+    expect(await svc().resolveInlineManual('user@x.eu', 'weather', { within })).toBeNull();
+    expect(paths).toEqual([expect.stringMatching(/weather\.tool$/)]);
+    expect(await svc().resolveInlineManual('user@x.eu', 'weather', { within: () => true })).not.toBeNull();
+  });
+
   test('resolves an inline tool that calls Google as a service account, and surfaces the key variable', async () => {
     // The auth block is what makes the call; the key it names has to reach the
     // secrets UI as a shared variable or nobody can store it.
@@ -486,6 +495,30 @@ describe('ToolManualService', () => {
     });
   });
 
+  /**
+   * A connection made as an `.agent` file narrows the catalog (`within`) —
+   * AFTER the read gate, on every read an agent surface makes, so it can take
+   * a manual away and never give one.
+   */
+  describe('narrowed to a connection’s connectors', () => {
+    const onlyBilling = (p: string) => p === 'Plugins/billing.tool';
+    const everything = () => true;
+
+    test('every agent-facing read answers only what is both readable and within', async () => {
+      const s = svc();
+      expect((await s.toManualCallTemplates('user@x.eu', { within: onlyBilling })).map((t) => t.name)).toEqual(['billing']);
+      expect((await s.listAccessibleCatalog('user@x.eu', onlyBilling)).tools.map((t) => t.name)).toEqual(['billing']);
+      expect(await s.catalogFingerprints('user@x.eu', onlyBilling)).toHaveLength(1);
+      expect(await s.listLocalOnly('user@x.eu', () => false)).toEqual([]);
+    });
+
+    test('an entry naming a manual the person may not read loads nothing for it', async () => {
+      const s = svc(denyBilling);
+      expect(await s.toManualCallTemplates('user@x.eu', { within: onlyBilling })).toEqual([]);
+      expect((await s.toManualCallTemplates('user@x.eu', { within: everything })).map((t) => t.name)).toEqual(['weather']);
+    });
+  });
+
   test('skips a `.tool` with a malformed `variables` entry (never silently mis-scoped)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsvbad-'));
     const tools = join(root, wsId, KB_DIR, 'Plugins');
@@ -920,6 +953,15 @@ describe('ToolManualService.listDeclaredOnlyOnBranch', () => {
     ]);
   });
 
+  test("narrowed to a connection's connectors, after the read gate", async () => {
+    await writeMcpJson(draftWs, 'Ops', ['pager']);
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DRAFT, (p) => p.startsWith('Plugins/Ops/'))).toEqual([
+      { name: 'pager', path: 'Plugins/Ops/mcp.json', type: 'mcp' },
+    ]);
+    // Naming an unreadable declaration does not let it through.
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DRAFT, (p) => p.startsWith('Plugins/Secret Plugin/'))).toEqual([]);
+  });
+
   test('is empty for the default branch itself and for a branch without a workspace', async () => {
     expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DEFAULT_BRANCH)).toEqual([]);
     expect(await svc().listDeclaredOnlyOnBranch('user@example.com', 'user/gone')).toEqual([]);

package/src/modules/tool-manuals/__tests__/tool-manuals.tools.test.ts

@@ -1,11 +1,13 @@
 import type { Server as HttpServer } from 'node:http';
 import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
-import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
-import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import { ToolRegistry } from '../../tool-registry/index.js';
+import {
+  InternalTokenService,
+  createToolAuthMiddleware,
+  createToolContextResolver,
+  createToolHandlerFactory,
+} from '../../../__tests__/tool-wiring.js';
 import { registerToolManualsTools } from '../tool-manuals.tools.js';
 import type { IToolManualService } from '../tool-manuals.contract.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -273,7 +275,7 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
       note?: string;
     };
     // Resolved for the caller, on the branch they named.
-    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm');
+    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm', undefined);
     // The released catalog is unchanged — the draft's server is not in it...
     expect(body.tools.map((t) => t.slug)).not.toContain('crm');
     // ...and the agent is told where it is and what makes it live.
@@ -294,7 +296,7 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
     const res = await callSetup(base, agentToken);
     expect(res.status).toBe(200);
     const body = (await res.json()) as { onBranchOnly: { name: string; branch: string }[]; note?: string };
-    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm');
+    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm', undefined);
     expect(body.onBranchOnly).toEqual([
       { name: 'crm', path: 'Plugins/Sales/mcp.json', type: 'mcp', branch: 'alice/add-crm' },
     ]);
@@ -311,7 +313,7 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
       onBranchOnly: { name: string }[];
     };
     expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledTimes(1);
-    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm');
+    expect(toolManualService.listDeclaredOnlyOnBranch).toHaveBeenCalledWith(ALICE.email, 'alice/add-crm', undefined);
     expect(body.onBranchOnly.map((p) => p.name)).toEqual(['crm']);
   });
 
@@ -337,3 +339,92 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
     expect(toolManualService.listDeclaredOnlyOnBranch).not.toHaveBeenCalled();
   });
 });
+
+describe('list_tool_setup — a tool that needs the caller’s own value says so', () => {
+  const TICKETS = {
+    slug: 'ticketdesk',
+    name: 'ticketdesk',
+    path: 'Plugins/Support/ticketdesk.tool',
+    type: 'http' as const,
+    variables: [{ name: 'TICKETDESK_TOKEN', scope: 'user' as const, label: null }],
+  };
+
+  it('tells a caller without their own value where to set it, and to reconnect', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [TICKETS], invalid: [] } as never);
+    // Bob has configured nothing (see `statusFor`).
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toContain('`ticketdesk` needs your own value or sign-in');
+    expect(body.note).toContain('Connect page, never in the chat');
+    expect(body.note).toContain('reconnect your assistant');
+  });
+
+  it('says nothing to a caller who has set theirs', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [TICKETS], invalid: [] } as never);
+    const body = (await (await callSetup(base, 'bevel_alice')).json()) as { note?: string };
+    expect(body.note).toBeUndefined();
+  });
+
+  const SIGN_IN = {
+    ...TICKETS,
+    variables: [{ name: 'TICKETDESK_OAUTH', scope: 'user' as const, label: null, oauth: { scopes: ['tickets'] } }],
+  };
+
+  /** The owner's side of a sign-in: a provider row of the OAuth kind. */
+  const ownerSignedUp = { adminConfigured: true, adminKind: 'oauth' as const };
+
+  it('tells a caller to sign in once the owner has set the sign-in up', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: false })),
+    );
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toContain('`ticketdesk` needs your own value or sign-in');
+  });
+
+  it('names a tool the proxy hides for a stale credential: the wrong kind, or a sign-in short of a scope', async () => {
+    const base = await start();
+    // A row left from when the variable was a plain key.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: true, userKind: 'static' as const })),
+    );
+    expect(((await (await callSetup(base, 'bevel_bob')).json()) as { note?: string }).note).toContain('`ticketdesk` needs your own value or sign-in');
+    // Signed in, but before the tool asked for `tickets`.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: true, userKind: 'oauth' as const, userAuthorized: true, grantedScopes: 'profile' })),
+    );
+    expect(((await (await callSetup(base, 'bevel_bob')).json()) as { note?: string }).note).toContain('`ticketdesk` needs your own value or sign-in');
+    // Signed in with the scope: nothing to say.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: true, userKind: 'oauth' as const, userAuthorized: true, grantedScopes: 'tickets' })),
+    );
+    expect(((await (await callSetup(base, 'bevel_bob')).json()) as { note?: string }).note).toBeUndefined();
+  });
+
+  it('does not send a caller to sign in before the owner has set the sign-in up', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, adminConfigured: false, userConfigured: false })),
+    );
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toBeUndefined();
+  });
+
+  it('does not send a caller to sign in on a shared key left from when the variable was static', async () => {
+    const base = await start();
+    // The owner turned a plain key into a sign-in; the old shared row is still
+    // there, so `adminConfigured` is true, but it is no provider to sign in to.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, adminConfigured: true, adminKind: 'static' as const, userConfigured: false })),
+    );
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toBeUndefined();
+  });
+});

package/src/modules/tool-manuals/index.ts

@@ -1,5 +1,8 @@
-export { ToolManualService } from './tool-manuals.service.js';
-export { PendingToolsService } from './pending-tools.service.js';
+// The services are types here: the composition root constructs them from
+// their files, so a module that imports this entry for a helper or a type
+// does not load the implementations.
+export type { ToolManualService } from './tool-manuals.service.js';
+export type { PendingToolsService } from './pending-tools.service.js';
 export { registerToolManualsTools } from './tool-manuals.tools.js';
 export {
   createToolManualsAgentRoutes,
@@ -7,6 +10,7 @@ export {
 } from './tool-manuals.routes.js';
 export {
   EXTERNAL_KB_MANUAL_NAME,
+  type ConnectorScope,
   type IPendingToolService,
   type IToolManualService,
   type PendingTool,