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

package/src/modules/tool-helpers/__tests__/agent-roles-write.test.ts

@@ -8,7 +8,7 @@ import { ToolRegistry } from '../../tool-registry/index.js';
 import {
   InternalTokenService,
   RoutineWritePolicyService,
-  WorkflowHooks,
+  VersionControlHooks,
   createToolAuthMiddleware,
   loadActiveGroups,
   registerWorkspaceTools,
@@ -50,7 +50,7 @@ async function start(): Promise<string> {
     getOrCreateForUser: async () => ({ id: WS }),
     getWorkspacePath: async () => root,
   } as never;
-  const workflowService = {
+  const versionControlService = {
     acquireLock: async () => ({ acquired: true, lock: { holderUserId: 'user-A', holderName: 'Admin' } }),
     releaseLock: async () => null,
     releaseLockNoCommit: async () => undefined,
@@ -59,7 +59,7 @@ async function start(): Promise<string> {
   const resolve = createToolContextResolver({
     authService,
     workspaceService,
-    workflowService,
+    versionControlService,
     events: {} as never,
     kbDirName: KB,
     creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
@@ -83,7 +83,7 @@ async function start(): Promise<string> {
   registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache, new WorkerDocumentExtractor()), allowAll, testKbContext({ kbDirName: KB }), {
     // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
-    hooks: new WorkflowHooks(),
+    hooks: new VersionControlHooks(),
     notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never);
   const app = express();

package/src/modules/tool-helpers/__tests__/branch-declaration.test.ts

@@ -10,7 +10,7 @@ import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import { BRANCH_REQUIRED_MESSAGE } from '../../../shared/domain-errors.js';
@@ -122,8 +122,8 @@ describe('a tool declares how it treats its branch', () => {
         getUserById: async () => ({ id: 'u', email: 'alice@example.com', name: 'Alice' }),
       } as unknown as AuthService,
       workspaceService: workspaces,
-      workflowService: {} as never,
-      events: { emit: () => {} } as unknown as WorkflowEventBus,
+      versionControlService: {} as never,
+      events: { emit: () => {} } as unknown as VersionControlEventBus,
       kbDirName: KB_DIR,
       creatorAccess: {} as ICreatorAccess,
     });

package/src/modules/tool-helpers/__tests__/can-write.tools.test.ts

@@ -14,7 +14,7 @@ import { ToolError, type ToolContext } from '../tool.contract.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
@@ -98,7 +98,7 @@ let readsNoted: { branch: string; wsPath: string }[] = [];
 let listingFails: Error | null = null;
 /** The refs the skill's committed files were listed at, in order. */
 let listedAt: string[] = [];
-const hooks = new WorkflowHooks();
+const hooks = new VersionControlHooks();
 hooks.onAgentRead(async ({ branch, wsPath = '' }) => {
   readsNoted.push({ branch, wsPath });
   if (refuseRead?.(branch, wsPath)) throw new ToolError('Not in this conversation.', 403);
@@ -171,7 +171,7 @@ beforeAll(async () => {
     sessionId,
     abortSignal: signal,
     workspaceService: workspaceService as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     getFilesystem: async (branch: string) => new LocalFilesystem({ basePath: wsDir(branch), contained: true }),
   });

package/src/modules/tool-helpers/__tests__/phase4-tools.test.ts

@@ -9,7 +9,7 @@ import { createToolHandlerFactory } from '../tool-handler.js';
 import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
@@ -45,7 +45,7 @@ const workspaceService = {
     throw new Error('no such file');
   },
 } as never;
-const workflowService = {} as never;
+const versionControlService = {} as never;
 const events = {} as never;
 const accessControl = {
   canRead: async () => true,
@@ -58,7 +58,7 @@ let httpServer: HttpServer | undefined;
 async function start(): Promise<string> {
   const registry = new ToolRegistry();
   const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
-  const resolve = createToolContextResolver({ authService, workspaceService, workflowService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
+  const resolve = createToolContextResolver({ authService, workspaceService, versionControlService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
   const th = createToolHandlerFactory(resolve);
   const router = express.Router();
   // NOTE (core split): this suite used to register the search, feedback and
@@ -68,7 +68,7 @@ async function start(): Promise<string> {
   registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), new DocExtractService('/tmp/bevel-test-doc-extract', new WorkerDocumentExtractor()), accessControl, testKbContext(), {
     // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
-    hooks: new WorkflowHooks(),
+    hooks: new VersionControlHooks(),
     notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never /* sessionSink — start_session not exercised here */);
   router.use(createManualRoutes(registry, toolAuth));

package/src/modules/tool-helpers/__tests__/tools-surface.test.ts

@@ -31,7 +31,7 @@ const workspaceService = {
   getOrCreateForUser: async () => ({ id: WS }),
   getWorkspacePath: async () => '/tmp/ws',
 } as never;
-const workflowService = { listBranches: async () => [{ name: 'main', isProtected: true }] } as never;
+const versionControlService = { listBranches: async () => [{ name: 'main', isProtected: true }] } as never;
 const events = {} as never;
 
 let httpServer: HttpServer | undefined;
@@ -40,7 +40,7 @@ const internalToken = new InternalTokenService({ secret: 'test-secret' });
 async function start(): Promise<string> {
   const registry = new ToolRegistry();
   const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
-  const resolve = createToolContextResolver({ authService, workspaceService, workflowService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
+  const resolve = createToolContextResolver({ authService, workspaceService, versionControlService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
   const toolHandler = createToolHandlerFactory(resolve);
 
   registry.registerExternalTool(
@@ -59,7 +59,7 @@ async function start(): Promise<string> {
     '/api/agent/tools/list_branches',
     toolAuth,
     toolHandler(async (_a: Record<string, unknown>, ctx: ToolContext) => ({
-      branches: await ctx.workflowService.listBranches('ws'),
+      branches: await ctx.versionControlService.listBranches('ws'),
       ranAs: ctx.user.id,
       source: ctx.source,
     })),

package/src/modules/tool-helpers/__tests__/validate-token.test.ts

@@ -35,7 +35,7 @@ const validateToken = createToolValidator({
   internalTokenService: internalToken,
   authService,
   workspaceService,
-  workflowService: {} as never,
+  versionControlService: {} as never,
   events: {} as never,
   kbDirName: 'knowledge-base',
   creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },

package/src/modules/tool-helpers/tool-context.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { LocalFilesystem } from '@mastra/core/workspace';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import { LockingFilesystem, ReadOnlyFilesystem } from '../kb-fs/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';
 import {
@@ -13,7 +13,7 @@ import type { WorkspaceService } from '../workspace/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { assertBranchProvided } from '../../shared/domain-errors.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
 import type { AuthService } from '../auth/index.js';
 import { ToolError, type ToolContext } from './tool.contract.js';
 import type { ToolAuth } from '../tool-auth/index.js';
@@ -22,8 +22,8 @@ import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope
 export interface ToolContextDeps {
   authService: AuthService;
   workspaceService: WorkspaceService;
-  workflowService: IWorkflowService;
-  events: WorkflowEventBus;
+  versionControlService: IVersionControlService;
+  events: VersionControlEventBus;
   /** KB dir name — used to recognise (and validate) writes to `roles.yaml`. */
   kbDirName: string;
   /**
@@ -139,7 +139,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
           ? new LockingFilesystem(
               { basePath, contained: true },
               {
-                workflow: deps.workflowService,
+                versionControl: deps.versionControlService,
                 workspaceId,
                 branch: branchForWorkspaceId(workspaceId),
                 user,
@@ -178,7 +178,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       focusedBranch: auth.source === 'internal' ? auth.focusedBranch : undefined,
       abortSignal,
       workspaceService: deps.workspaceService,
-      workflowService: deps.workflowService,
+      versionControlService: deps.versionControlService,
       events: deps.events,
       getFilesystem,
       getWriteValidator,

package/src/modules/tool-helpers/tool-handler.ts

@@ -7,7 +7,7 @@ import {
   assertBranchProvided,
   BranchNotFoundError,
   DefaultBranchUnsetError,
-  WorkflowDomainError,
+  VersionControlDomainError,
 } from '../../shared/domain-errors.js';
 import { branchHandlingFor, type BranchHandling } from './tool-def.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
@@ -323,7 +323,7 @@ export function createToolHandlerFactory(
           // payload) — so a tool caller
           // switching on `branch-not-found` vs `remote-branch-gone` does not
           // have to read the prose to tell them apart.
-          if (err instanceof WorkflowDomainError) {
+          if (err instanceof VersionControlDomainError) {
             res.status(err.status).json(domainErrorBody(err));
             return;
           }

package/src/modules/tool-helpers/tool.contract.ts

@@ -1,8 +1,8 @@
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { ConnectionScope } from '../agent-scope/index.js';
 import type { LocalFilesystem } from '@mastra/core/workspace';
 import type { WorkspaceService } from '../workspace/index.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';
 
 /**
@@ -70,8 +70,8 @@ export interface ToolContext {
   connectionScope?: ConnectionScope;
   abortSignal: AbortSignal;
   workspaceService: WorkspaceService;
-  workflowService: IWorkflowService;
-  events: WorkflowEventBus;
+  versionControlService: IVersionControlService;
+  events: VersionControlEventBus;
   /** Build the lock-aware filesystem for `branch`'s workspace (cached). The tool supplies `branch` from its own input. */
   getFilesystem(branch: string): Promise<LocalFilesystem>;
   /**

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

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'vitest';
-import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, type ChangeRequest, type IVersionControlService } from '@bevel-software/platform-shared';
 import { PendingToolsService } from '../pending-tools.service.js';
 import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
@@ -90,11 +90,11 @@ function harness(opts: {
     listAllSummaries: async () => (opts.released ?? []) as ToolManualSummary[],
   } as unknown as IToolManualService;
 
-  const workflow = {
+  const versionControl = {
     listChangeRequests: async () => opts.crs,
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 
-  return new PendingToolsService(workspaceService, accessControl, toolManuals, workflow, testKbContext());
+  return new PendingToolsService(workspaceService, accessControl, toolManuals, versionControl, testKbContext());
 }
 
 const ADMIN_WRITES = { [TOOL_PATH]: [ADMIN] };
@@ -357,20 +357,20 @@ describe('PendingToolsService', () => {
   });
 
   /**
-   * This hangs off the library's list load. A workflow service that cannot
+   * This hangs off the library's list load. A version-control service that cannot
    * answer must cost the reader an empty review shelf, not their whole library.
    */
   test('degrades to nothing pending when the change requests cannot be listed', async () => {
-    const workflow = {
+    const versionControl = {
       listChangeRequests: async () => {
         throw new Error('offline');
       },
-    } as unknown as IWorkflowService;
+    } as unknown as IVersionControlService;
     const svc = new PendingToolsService(
       {} as unknown as WorkspaceService,
       {} as unknown as IAccessControl,
       { listAllSummaries: async () => [] } as unknown as IToolManualService,
-      workflow,
+      versionControl,
       testKbContext(),
     );
     await expect(svc.listPendingTools(AUTHOR)).resolves.toEqual([]);
@@ -385,7 +385,7 @@ describe('PendingToolsService', () => {
           throw new Error('workspace gone');
         },
       } as unknown as IToolManualService,
-      { listChangeRequests: async () => [cr()] } as unknown as IWorkflowService,
+      { listChangeRequests: async () => [cr()] } as unknown as IVersionControlService,
       testKbContext(),
     );
     await expect(svc.listPendingTools(AUTHOR)).resolves.toEqual([]);

package/src/modules/tool-manuals/__tests__/tool-manuals.managed-sign-in.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'vitest';
+import { normalizeToolManual } from '../tool-manuals.service.js';
+
+/**
+ * A sign-in that goes through a managed connector: the `oauth` block names
+ * the connector instead of a client id, and — for a workspace connection —
+ * may sit on an `admin`-scoped variable, the one case an OAuth block may.
+ */
+function manual(variable: Record<string, unknown>): string {
+  return JSON.stringify({
+    id: 'microsoft365',
+    type: 'inline',
+    variables: [variable],
+    tools: [
+      {
+        name: 'list_mail',
+        description: 'List mail.',
+        inputs: { type: 'object', properties: {} },
+        outputs: { type: 'object', properties: {} },
+        tool_call_template: {
+          call_template_type: 'http',
+          http_method: 'GET',
+          url: 'https://graph.microsoft.com/v1.0/me/messages',
+          headers: { Authorization: 'Bearer ${ACCESS_TOKEN}' },
+        },
+      },
+    ],
+  });
+}
+
+const ENDPOINTS = {
+  authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+  tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+};
+
+describe('a managed sign-in in a .tool', () => {
+  test('parses without a clientId when `managed` names the connector and scope set', () => {
+    const d = normalizeToolManual('m', 'Plugins/x/m.tool', manual({
+      name: 'ACCESS_TOKEN',
+      scope: 'user',
+      oauth: { ...ENDPOINTS, scopes: ['Mail.Read'], managed: { connectorId: 'microsoft365', scopeSet: 'read' } },
+    }));
+    expect(d.variables?.[0].oauth).toEqual({
+      ...ENDPOINTS,
+      scopes: ['Mail.Read'],
+      managed: { connectorId: 'microsoft365', scopeSet: 'read' },
+    });
+    expect(d.variables?.[0].oauth?.clientId).toBeUndefined();
+  });
+
+  test('still requires a clientId on an ordinary sign-in', () => {
+    expect(() =>
+      normalizeToolManual('m', 'Plugins/x/m.tool', manual({ name: 'ACCESS_TOKEN', scope: 'user', oauth: { ...ENDPOINTS } })),
+    ).toThrow(/clientId/);
+  });
+
+  test('refuses a malformed `managed` reference without repeating it', () => {
+    expect(() =>
+      normalizeToolManual('m', 'Plugins/x/m.tool', manual({
+        name: 'ACCESS_TOKEN',
+        scope: 'user',
+        oauth: { ...ENDPOINTS, managed: { connectorId: 'Micro Soft!', scopeSet: 'read' } },
+      })),
+    ).toThrow(/`variables\[0\]\.oauth\.managed` must be/);
+  });
+
+  test('refuses a sign-in that names both `managed` and a `clientId`: one client, not two flows', () => {
+    expect(() =>
+      normalizeToolManual('m', 'Plugins/x/m.tool', manual({
+        name: 'ACCESS_TOKEN',
+        scope: 'user',
+        oauth: { ...ENDPOINTS, clientId: 'own', managed: { connectorId: 'microsoft365', scopeSet: 'read' } },
+      })),
+    ).toThrow(/names both `managed` and a `clientId`/);
+  });
+
+  test('a workspace connection: `oauth` on an `admin` variable is allowed only when managed', () => {
+    const shared = normalizeToolManual('m', 'Plugins/x/m.tool', manual({
+      name: 'ACCESS_TOKEN',
+      scope: 'admin',
+      oauth: { ...ENDPOINTS, managed: { connectorId: 'hubspot', scopeSet: 'read' } },
+    }));
+    expect(shared.variables?.[0]).toMatchObject({ scope: 'admin', oauth: { managed: { connectorId: 'hubspot' } } });
+
+    expect(() =>
+      normalizeToolManual('m', 'Plugins/x/m.tool', manual({ name: 'ACCESS_TOKEN', scope: 'admin', oauth: { ...ENDPOINTS, clientId: 'c' } })),
+    ).toThrow(/scope` must be `user`/);
+  });
+});

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

@@ -207,7 +207,7 @@ describe('external tools and their sign-ins across a restart', () => {
       createToolContextResolver({
         authService: { getUserById: async (id: string) => (id === USER.id ? { ...USER, name: 'User' } : null) } as never,
         workspaceService: { getWorkspacePath: async () => root } as never,
-        workflowService: {} as never,
+        versionControlService: {} as never,
         events: {} as never,
         kbDirName: KB_DIR,
         creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },

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

@@ -117,7 +117,7 @@ async function start(hiddenTools?: HiddenToolSource): Promise<string> {
       getUserById: async (id: string) => (id === ALICE.id ? ALICE : id === BOB.id ? BOB : null),
     } as never,
     workspaceService: { getWorkspacePath: async () => '/tmp/ws' } as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     kbDirName: 'knowledge-base',
     creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
@@ -374,6 +374,41 @@ describe('list_tool_setup — a tool that needs the caller’s own value says so
   /** The owner's side of a sign-in: a provider row of the OAuth kind. */
   const ownerSignedUp = { adminConfigured: true, adminKind: 'oauth' as const };
 
+  /** A managed connector enabled as ONE workspace connection: the sign-in sits on an `admin` variable. */
+  const SHARED_SIGN_IN = {
+    ...TICKETS,
+    variables: [
+      {
+        name: 'ACCESS_TOKEN',
+        scope: 'admin' as const,
+        label: 'Ticketdesk sign-in',
+        oauth: { scopes: ['tickets'], managed: { connectorId: 'ticketdesk', scopeSet: 'read' } },
+      },
+    ],
+  };
+
+  it('a workspace connection is authorized only while the owner’s token covers the declared scopes, and names its connector', async () => {
+    const base = await start();
+    const authorizedOf = async (status: Record<string, unknown>) => {
+      vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SHARED_SIGN_IN], invalid: [] } as never);
+      statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+        keys.map((key) => ({ key, adminConfigured: true, adminKind: 'oauth' as const, userConfigured: false, ...status })),
+      );
+      const body = (await (await callSetup(base, 'bevel_bob')).json()) as {
+        tools: { variables: { authorized: boolean | null; managed?: unknown }[] }[];
+      };
+      return body.tools[0].variables[0];
+    };
+    // Connected by an owner, but before the tool asked for `tickets`.
+    expect((await authorizedOf({ adminAuthorized: true, adminGrantedScopes: 'profile' })).authorized).toBe(false);
+    // Connected with a covering token: everyone's, Bob's included.
+    const connected = await authorizedOf({ adminAuthorized: true, adminGrantedScopes: 'profile tickets' });
+    expect(connected.authorized).toBe(true);
+    expect(connected.managed).toEqual({ connectorId: 'ticketdesk', scopeSet: 'read' });
+    // Nobody has connected it yet.
+    expect((await authorizedOf({ adminAuthorized: false })).authorized).toBe(false);
+  });
+
   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);

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -368,7 +368,7 @@ export class McpServerEditService {
     // COMMIT must not — the pending-commit pipeline may already have created
     // a local commit before the push refused, and rewriting the working tree
     // to pre-edit bytes would leave it dirty AGAINST that commit, a state the
-    // workflow layer's own pull-rebase recovery then misreads. Commit-stage
+    // version-control layer's own pull-rebase recovery then misreads. Commit-stage
     // failures propagate as-is and the pipeline's recovery owns the cleanup.
     const [mcpBefore, manifestBefore] = await Promise.all([
       fs.readFile(mcpAbs, 'utf8').catch(() => null),

package/src/modules/tool-manuals/pending-tools.service.ts

@@ -3,7 +3,7 @@ import {
   PLUGIN_MCP_FILE,
   pluginOfPath,
   type ChangeRequest,
-  type IWorkflowService,
+  type IVersionControlService,
   type KbLayout,
 } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/index.js';
@@ -54,7 +54,7 @@ export class PendingToolsService implements IPendingToolService {
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
     private readonly toolManuals: Pick<IToolManualService, 'listAllSummaries'>,
-    private readonly workflow: IWorkflowService,
+    private readonly versionControl: IVersionControlService,
     private readonly kb: KbContext,
   ) {}
 
@@ -77,7 +77,7 @@ export class PendingToolsService implements IPendingToolService {
       {
         workspaceService: this.workspaceService,
         accessControl: this.accessControl,
-        workflow: this.workflow,
+        versionControl: this.versionControl,
         kb: this.kb,
       },
       userEmail,

package/src/modules/tool-manuals/tool-delete.service.ts

@@ -331,7 +331,7 @@ export class ToolDeleteService {
       // THEN pushes, so a refused push leaves a commit that already removed
       // the file: renaming it back there would leave the working tree dirty
       // against HEAD — re-adding, on the next commit, the very tool this one
-      // deleted, which is the state the workflow layer's own recovery
+      // deleted, which is the state the version-control layer's own recovery
       // misreads (McpServerEditService refuses to touch the tree for the same
       // reason). A probe that itself fails counts as "a commit may exist": the
       // park survives, dot-prefixed and invisible to the scanner, for a person

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

@@ -52,7 +52,12 @@ export interface ToolVariableOAuth {
   /** Absent on an mcp.json server ⇒ discovered from the server's OAuth metadata. */
   authorizationUrl?: string;
   tokenUrl?: string;
-  clientId: string;
+  /**
+   * Required on an ordinary sign-in. Absent ONLY on a managed one (see
+   * `managed`), whose client is Bevel's and lives on the broker; an owner who
+   * brings their own app supplies it on the client-secret route instead.
+   */
+  clientId?: string;
   scopes?: string[];
   /**
    * Extra static query params appended to the authorization request — e.g.
@@ -77,6 +82,21 @@ export interface ToolVariableOAuth {
    * endpoints are declared by hand too.
    */
   resource?: string;
+  /**
+   * The sign-in goes through Bevel's managed OAuth app for a platform
+   * connector: the broker does the provider round-trip and hands the tokens
+   * to this deployment, and renews them on its behalf. Written by the
+   * connector template an admin enables; `clientId` is then absent. The
+   * broker decides the scopes it requests from its own copy of the
+   * connector's definition, so an edited file cannot widen them.
+   */
+  managed?: ManagedSignIn;
+}
+
+/** Which managed connector and scope set a sign-in belongs to. */
+export interface ManagedSignIn {
+  connectorId: string;
+  scopeSet: string;
 }
 
 /**
@@ -93,8 +113,11 @@ export interface ToolVariable {
   label?: string;
   /**
    * When present, this variable is OAuth-backed: the user signs in with the
-   * declared provider to obtain a token. Only valid with `scope:'user'` (each
-   * caller authorizes their own). The client secret is NOT declared here.
+   * declared provider to obtain a token. Valid with `scope:'user'` (each
+   * caller authorizes their own), or with `scope:'admin'` ONLY for a managed
+   * sign-in — one workspace connection an owner makes, read by every caller
+   * (the shared row then holds the tokens). The client secret is NOT
+   * declared here.
    */
   oauth?: ToolVariableOAuth;
 }
@@ -525,6 +548,21 @@ export interface IToolManualService {
   ): Promise<
     { key: string; name: string; label: string | null; oauth: boolean; oauthScopes?: string[] }[]
   >;
+  /**
+   * The SHARED (`admin`-scoped) sign-ins a manual declares — a managed
+   * connector enabled as a workspace connection. The pre-call check reads
+   * these so a tool whose one connection nobody has made yet is reported as
+   * missing its sign-in, labelled "(a tool owner connects this for the
+   * workspace)", instead of failing opaquely at the provider.
+   *
+   * `key` is the vault key as UTCP derives it (`utcpNamespacedKey`): the
+   * manual's name with every non-word character made `_` and every `_` then
+   * doubled, an `_`, and the variable's name (`my-tool` + `ACCESS_TOKEN` →
+   * `my__tool_ACCESS_TOKEN`). Read it from here; never compose it by hand.
+   */
+  sharedSignInKeysForManual(
+    manualName: string,
+  ): Promise<{ key: string; name: string; label: string | null; oauthScopes?: string[] }[]>;
   /** Drop the cached catalog (call after a merge to the default branch). */
   invalidate(): void;
 }