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

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -3,7 +3,7 @@ import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
@@ -26,8 +26,8 @@ const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
 const MIA = { id: 'u-mia', email: 'mia@x.io', name: 'Mia' };
 const FOLDER = 'Skills/Eng/deploy';
 
-async function makeHarness(listBranches: IWorkflowService['listBranches']) {
-  const workflow = {
+async function makeHarness(listBranches: IVersionControlService['listBranches']) {
+  const versionControl = {
     listChangeRequests: vi.fn(async () => []),
     listBranches: vi.fn(listBranches),
     createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
@@ -35,7 +35,7 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
     commitChanges: vi.fn(async () => null),
     openChangeRequest: vi.fn(async () => ({ number: 42 })),
     getChangeRequestDetail: vi.fn(async () => ({ body: '' })),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
   const workspaceService = {
     getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: workspaceIdForBranch(branch) })),
     readFile: vi.fn(async () => '---\n---\nwrite:\n  - Eve <eve@x.io>\n'),
@@ -57,8 +57,8 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
     createSkillAccessRequestRoutes({
       skillService,
       accessControl,
-      workflow,
-      requests: new AccessRequestsService({ workflow, workspaceService, lifecycle: joinRequests, kb }),
+      versionControl,
+      requests: new AccessRequestsService({ versionControl, workspaceService, lifecycle: joinRequests, kb }),
       joinRequests,
       kb,
       resolveUser: async () => MIA,
@@ -68,7 +68,7 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
     const s = app.listen(0, () => resolve(s));
   });
   const { port } = server.address() as AddressInfo;
-  return { server, url: `http://127.0.0.1:${port}/api/skills/deploy/access-request`, workflow, workspaceService };
+  return { server, url: `http://127.0.0.1:${port}/api/skills/deploy/access-request`, versionControl, workspaceService };
 }
 
 describe('POST /skills/:name/access-request — the branch probe', () => {
@@ -87,11 +87,11 @@ describe('POST /skills/:name/access-request — the branch probe', () => {
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ ok: true, number: 42 });
-    expect(h.workflow.listBranches).toHaveBeenCalledWith(wsId, { freshFetch: true, strictFetch: true });
-    expect(h.workflow.createBranch).toHaveBeenCalledWith(wsId, joinBranchFor(MIA.email, FOLDER), DEFAULT_BRANCH);
+    expect(h.versionControl.listBranches).toHaveBeenCalledWith(wsId, { freshFetch: true, strictFetch: true });
+    expect(h.versionControl.createBranch).toHaveBeenCalledWith(wsId, joinBranchFor(MIA.email, FOLDER), DEFAULT_BRANCH);
     // The whole chain the probe exists to enable: the grant is written AND committed.
     expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
-    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+    expect(h.versionControl.commitChanges).toHaveBeenCalledTimes(1);
   });
 
   it('a create that loses the race proceeds once the fresh re-probe shows the branch', async () => {
@@ -99,26 +99,26 @@ describe('POST /skills/:name/access-request — the branch probe', () => {
     // Absent on the first probe, present on the second: someone else cut it in between.
     let probes = 0;
     const h = await makeHarness(async () => (probes++ === 0 ? [] : [{ name: branch, isDefault: false, isProtected: false }]));
-    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('already exists'));
+    (h.versionControl.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('already exists'));
     server = h.server;
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ ok: true, number: 42 });
-    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.versionControl.listBranches).toHaveBeenCalledTimes(2);
     expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
-    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+    expect(h.versionControl.commitChanges).toHaveBeenCalledTimes(1);
   });
 
   it('a create that fails with no branch to show for it stops the request — nothing is written on a branch that was not made', async () => {
     vi.spyOn(console, 'error').mockImplementation(() => {});
     const h = await makeHarness(async () => []);
-    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('origin refused'));
+    (h.versionControl.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('origin refused'));
     server = h.server;
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(500);
-    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.versionControl.listBranches).toHaveBeenCalledTimes(2);
     expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+    expect(h.versionControl.openChangeRequest).not.toHaveBeenCalled();
   });
 
   it('a listing that could not prove anything stops the request before a branch or a byte is written', async () => {
@@ -129,8 +129,8 @@ describe('POST /skills/:name/access-request — the branch probe', () => {
     server = h.server;
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(500);
-    expect(h.workflow.createBranch).not.toHaveBeenCalled();
+    expect(h.versionControl.createBranch).not.toHaveBeenCalled();
     expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+    expect(h.versionControl.openChangeRequest).not.toHaveBeenCalled();
   });
 });

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

@@ -12,8 +12,8 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import { readFile as fsReadFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { GitService } from '../../workflow/git/git.service.js';
+import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
+import { GitService } from '../../version-control/git/git.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const execFileAsync = promisify(execFile);
@@ -423,7 +423,7 @@ describe('SkillService', () => {
 
     const versioned = (access: IAccessControl = allowAll) => {
       const service = svc(access);
-      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), testKbContext({ kbDirName: KB_DIR })));
+      service.setHistory(new GitService(workspaceService, new VersionControlHooks(), testKbContext({ kbDirName: KB_DIR })));
       return service;
     };
 

package/src/modules/skills/pending-skills.service.ts

@@ -1,4 +1,4 @@
-import type { KbLayout, IWorkflowService } from '@bevel-software/platform-shared';
+import type { KbLayout, IVersionControlService } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from '../access/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
@@ -36,7 +36,7 @@ export class PendingSkillsService implements IPendingSkillService {
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
     private readonly skillService: ISkillService,
-    private readonly workflow: IWorkflowService,
+    private readonly versionControl: IVersionControlService,
     private readonly kb: KbContext,
   ) {}
 
@@ -57,7 +57,7 @@ export class PendingSkillsService implements IPendingSkillService {
       {
         workspaceService: this.workspaceService,
         accessControl: this.accessControl,
-        workflow: this.workflow,
+        versionControl: this.versionControl,
         kb: this.kb,
       },
       userEmail,

package/src/modules/skills/skill-access-requests.routes.ts

@@ -3,10 +3,10 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('skills');
 import '../auth/index.js'; // Express Request.userId / userEmail augmentation
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl, IAccessRequests } from '../access/index.js';
 import { folderTarget } from '../access/index.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { JoinRequestsService } from '../plugins/index.js';
@@ -34,14 +34,14 @@ import type { ISkillService } from './skills.contract.js';
 export function createSkillAccessRequestRoutes(deps: {
   skillService: ISkillService;
   accessControl: IAccessControl;
-  workflow: IWorkflowService;
+  versionControl: IVersionControlService;
   /** Opens an access request — the same opener the Manage access dialog uses, wired by the composition root. */
   requests: IAccessRequests;
   joinRequests: JoinRequestsService;
   kb: KbContext;
   resolveUser: (req: express.Request) => Promise<AuthUser | null>;
 }): express.Router {
-  const { skillService, accessControl, workflow, requests, joinRequests, kb, resolveUser } = deps;
+  const { skillService, accessControl, versionControl, requests, joinRequests, kb, resolveUser } = deps;
   const router = express.Router();
   const wsId = () => kb.defaultWorkspaceId();
   const rulesOf = (folder: string) => `${folder}/access.md`;
@@ -85,7 +85,7 @@ export function createSkillAccessRequestRoutes(deps: {
       });
       res.json({ ok: true, number });
     } catch (err) {
-      if (err instanceof WorkflowDomainError) {
+      if (err instanceof VersionControlDomainError) {
         res.status(err.status).json(domainErrorBody(err));
         return;
       }
@@ -113,7 +113,7 @@ export function createSkillAccessRequestRoutes(deps: {
     try {
       const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
       if (!ctx) return;
-      const crs = await workflow.listChangeRequests();
+      const crs = await versionControl.listChangeRequests();
       res.json({ requests: await joinRequests.list(ctx.folder, folderTarget(ctx.folder), crs, ctx.user) });
     } catch (err) {
       log.error('failed to list access requests:', { err });
@@ -130,7 +130,7 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(400).json({ error: 'Invalid change request number' });
         return;
       }
-      const cr = await workflow.getChangeRequest(crNumber);
+      const cr = await versionControl.getChangeRequest(crNumber);
       if (!cr) {
         res.status(404).json({ error: 'Not found' });
         return;

package/src/modules/skills/skills.tools.ts

@@ -33,7 +33,7 @@ const LIST_SKILLS_INPUTS = {
 const GET_SKILL_INPUTS = {
   type: 'object' as const,
   properties: {
-    name: { type: 'string' as const, minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
+    name: { type: 'string' as const, minLength: 1, description: 'Skill name, as `list_skills` gives it (its `id`, else its `name`, else its folder name; e.g. `rfi`).' },
     file: {
       type: 'string' as const,
       description:

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

@@ -4,21 +4,27 @@ import os from 'node:os';
 import path from 'node:path';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it } 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 { ToolRegistry } from '../../tool-registry/index.js';
+import {
+  InternalTokenService,
+  RoutineWritePolicyService,
+  VersionControlHooks,
+  createToolAuthMiddleware,
+  loadActiveGroups,
+  registerWorkspaceTools,
+} from '../../../__tests__/tool-wiring.js';
 import { createToolContextResolver } from '../tool-context.js';
 import { createToolHandlerFactory } from '../tool-handler.js';
-import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
-import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
-import { SpillStore } from '../../workspace/spill-store.js';
-import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
-import { NEW_ROLE_GUIDANCE } from '../../access-model/roles-yaml-guard.js';
-import { loadActiveGroups } from '../../access/access-control.service.js';
+import { DocExtractService, SpillStore, ToolDescriptionNotes, WorkerDocumentExtractor } from '../../workspace/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
+/**
+ * The sentence a refused role creation carries to the agent, as the agent
+ * guide states it too: asserted as the words a person reads, not as the
+ * module's constant, so a reworded refusal is a visible change here.
+ */
+const NEW_ROLE_GUIDANCE = 'add people to existing roles, and use a GROUP for a task- or team-scoped set of people';
+
 /**
  * The agent's file tools over the production context resolver and a real
  * workspace on disk: a roles.yaml write that creates a role is refused with a
@@ -44,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,
@@ -53,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: () => {} },
@@ -71,11 +77,13 @@ async function start(): Promise<string> {
     canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
     // The `after` half of a move's or copy's preview — allowing everything, like the gates above.
     previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
+    // Who else loses or gains access in a move: nobody, here.
+    prospectiveHolderChanges: async () => ({ lose: [], gain: [] }),
   } as never;
   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__/route-tool-schemas.catalog.test.ts

@@ -0,0 +1,38 @@
+import { compileCheck, exampleArguments } from '@bevel-software/platform-mcp-core';
+import { describe, expect, it } from 'vitest';
+import { hexisCatalog } from '../../../__tests__/hexis-catalog.js';
+import { routeToolSchemas } from '../route-tool-schemas.js';
+
+/**
+ * Every tool a route mounts declares two schemas: the one a client sees
+ * (`inputs`, with the platform tools' arguments under `body`) and the FLAT one
+ * the route itself checks a call against. The `Call:` line at the top of each
+ * description is generated from the first; the route refuses by the second.
+ * The two must agree, or a call written from the example is refused one
+ * layer in, with nothing in the description to say why.
+ *
+ * Held here, over the whole catalog Hexis registers, because the flat schema
+ * is this module's: `routeToolSchemas` is how a mounted route finds its own,
+ * and no other module reads it.
+ */
+describe('the flat schema a route checks against accepts the call its own example shows', () => {
+  it('for every tool Hexis mounts on a route', async () => {
+    const { internal } = await hexisCatalog();
+    const mounted = internal.filter((tool) => routeToolSchemas(tool.name) !== undefined);
+    // The catalog is the real one: the family every scenario names is in it.
+    for (const name of ['read_file', 'write_file', 'list_files', 'grep', 'move_file']) {
+      expect(mounted.some((t) => t.name === name), name).toBe(true);
+    }
+    expect(mounted.length).toBeGreaterThan(12);
+    for (const tool of mounted) {
+      // The client's schema is the flat one in its envelope (`bodyEnvelope`),
+      // so the client's example and the route's check meet on the flat schema:
+      // an example written from it must pass the check made from it.
+      const flat = routeToolSchemas(tool.name)!.flat;
+      const check = compileCheck(flat);
+      expect(check.checkable, `${tool.name} (flat): ${check.checkable ? '' : check.reason}`).toBe(true);
+      if (!check.checkable) throw new Error(check.reason);
+      expect(check.check(exampleArguments(flat)), `${tool.name} (flat)`).toEqual([]);
+    }
+  });
+});

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-def.ts

@@ -16,7 +16,7 @@ const toolSerializer = new ToolSerializer();
 export const BRANCH_INPUT: JsonSchema = {
   type: 'string',
   minLength: 1,
-  description: 'The branch (draft) whose workspace this operates on — pass the branch you are currently working on.',
+  description: 'The branch to work on: the default branch (`get_agent_guide` names it) or your draft.',
 };
 
 /**

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([]);