@bevel-software/platform-core-backend 0.20.0 → 0.22.0

package/src/modules/workflow/__tests__/workflow.service.update-from-target.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import type { AuthUser, PullRequestDetail } from '@bevel-software/platform-shared';
 import type { GitService } from '../git/git.service.js';
 import type { PullRequestService } from '../git/pull-request.service.js';
@@ -44,17 +45,26 @@ function detail(overrides: Partial<PullRequestDetail> = {}): PullRequestDetail {
     branch: 'alice/deal',
     base: 'current-company-state',
     behind: true,
+    needsUpdate: true,
     viewerCanUpdate: true,
     headSha: HEAD,
     mergeBaseSha: 'c'.repeat(40),
+    // The pre-flight read asks for no patches, but it still names the files —
+    // which is what the fallback for a failed diff answers with.
+    files: [{ path: 'Sales/Deal.md' }],
     ...overrides,
-  } as PullRequestDetail;
+  } as unknown as PullRequestDetail;
 }
 
 function harness(opts: {
   first?: PullRequestDetail | null;
   /** The published head of the proposal branch as resolved just before the merge. */
   publishedHead?: string;
+  /**
+   * The published head AFTER the merge. Defaults to the merge commit; set it
+   * equal to the pre-merge head to describe a merge that moved nothing.
+   */
+  headAfterMerge?: string;
   resolveError?: Error;
   merge?: { kind: 'clean'; alreadyUpToDate: boolean } | { kind: 'conflicts'; paths: string[] };
   pullError?: Error;
@@ -63,31 +73,42 @@ function harness(opts: {
   changedPathsError?: Error;
   /** How many approval rows the carry-forward wrote. */
   carried?: number;
-  /** The detail the extra read after a carry-forward answers with. */
-  withApprovals?: PullRequestDetail;
+  /** Does the clone hold commits origin has not seen? */
+  unpushed?: boolean;
+  unpushedError?: Error;
 }) {
+  // Two resolves per update: once after the pull (where the branch IS), once
+  // after the merge (where it ended up). One mock that answers in order, so a
+  // test can describe a head that moved without stubbing call indices.
+  const preMergeHead = opts.publishedHead ?? HEAD;
+  const postMergeHead = opts.headAfterMerge ?? MERGED_HEAD;
+  const resolvePrShas = opts.resolveError
+    ? vi.fn().mockRejectedValue(opts.resolveError)
+    : vi
+        .fn()
+        .mockResolvedValueOnce({ baseSha: 'b'.repeat(40), headSha: preMergeHead })
+        .mockResolvedValue({ baseSha: 'b'.repeat(40), headSha: postMergeHead });
   const git = {
     pull: opts.pullError
       ? vi.fn().mockRejectedValue(opts.pullError)
       : vi.fn().mockResolvedValue({ treeChanged: false }),
     mergeFromOrigin: vi.fn().mockResolvedValue(opts.merge ?? { kind: 'clean', alreadyUpToDate: false }),
     push: vi.fn().mockResolvedValue(undefined),
+    hasUnpushedCommits: opts.unpushedError
+      ? vi.fn().mockRejectedValue(opts.unpushedError)
+      : vi.fn().mockResolvedValue(opts.unpushed ?? true),
     pathsChangedBetween: opts.changedPathsError
       ? vi.fn().mockRejectedValue(opts.changedPathsError)
       : vi.fn().mockResolvedValue(opts.changedPaths ?? []),
-    resolvePrShas: opts.resolveError
-      ? vi.fn().mockRejectedValue(opts.resolveError)
-      : vi.fn().mockResolvedValue({
-          baseSha: 'b'.repeat(40),
-          headSha: opts.publishedHead ?? HEAD,
-        }),
+    resolvePrShas,
   };
-  const refreshed = detail({ behind: false, headSha: MERGED_HEAD });
+  const refreshed = detail({ behind: false, needsUpdate: false, headSha: postMergeHead });
+  // Exactly two reads per update: the pre-flight (authority, branch names)
+  // and the one that goes back. A third would be the cost this ticket removed.
   const getPrDetail = vi
     .fn()
     .mockResolvedValueOnce(opts.first === undefined ? detail() : opts.first)
-    .mockResolvedValueOnce(refreshed)
-    .mockResolvedValue(opts.withApprovals ?? refreshed);
+    .mockResolvedValue(refreshed);
   const prs = { getPrDetail, invalidateDetailCache: vi.fn() };
   const pendingCommits = { enqueueIfAbsent: vi.fn().mockResolvedValue(true) };
   const reviewWorkflow = {
@@ -102,7 +123,7 @@ function harness(opts: {
     {} as unknown as IAccessControl,
     {} as unknown as FileLockService,
     pendingCommits as unknown as PendingCommitsService,
-    'knowledge-base',
+    testKbContext(),
     openChangeGate(),
   );
   return { svc, git, prs, pendingCommits, reviewWorkflow, refreshed };
@@ -110,14 +131,19 @@ function harness(opts: {
 
 describe('WorkflowService.updateFromTarget', () => {
   it('merges the target into the proposal, pushes, and returns the refreshed detail', async () => {
-    const h = harness({});
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    const h = harness({ changedPaths: ['Sales/Deal.md'] });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: ['Sales/Deal.md'],
+    });
 
-    // The permission read is computed for THIS caller.
+    // The permission read is computed for THIS caller — and asks for no
+    // patches: all it decides is authority, state and the two branch names.
     expect(h.prs.getPrDetail).toHaveBeenNthCalledWith(1, 7, {
       fresh: true,
       workspaceId: WS,
       viewerEmail: USER.email,
+      patches: false,
     });
     expect(h.git.mergeFromOrigin).toHaveBeenCalledWith(WS, 'alice/deal', 'current-company-state', USER);
     expect(h.git.push).toHaveBeenCalledWith(WS, USER);
@@ -125,6 +151,29 @@ describe('WorkflowService.updateFromTarget', () => {
     expect(h.refreshed.behind).toBe(false);
   });
 
+  it('costs ONE detail read after the merge', async () => {
+    // The whole point of the ticket on the server side. Two reads total: the
+    // pre-flight that decides authority, and the one that goes back. The
+    // carry-forward runs BEFORE that second read rather than correcting it
+    // with a third.
+    const h = harness({ changedPaths: ['Sales/Deal.md'], carried: 2 });
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(2);
+    const carriedAt = h.reviewWorkflow.carryApprovalsForward.mock.invocationCallOrder[0];
+    const lastReadAt = h.prs.getPrDetail.mock.invocationCallOrder[1];
+    expect(carriedAt).toBeLessThan(lastReadAt);
+  });
+
+  it('replays the pull with --rebase-merges, so an unpushed merge stays a merge', async () => {
+    // A plain rebase flattens a merge commit origin has not seen into
+    // cherry-picks of the target's commits, which drops the target as a
+    // parent — and the request never contains the target's head however many
+    // times the update runs.
+    const h = harness({});
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.git.pull).toHaveBeenCalledWith(WS, { preserveMerges: true });
+  });
+
   it('refuses a viewer who is neither the author nor able to apply — nothing is merged', async () => {
     const h = harness({ first: detail({ viewerCanUpdate: false }) });
     const err = await h.svc.updateFromTarget(WS, USER, 7).catch((e: unknown) => e);
@@ -156,13 +205,54 @@ describe('WorkflowService.updateFromTarget', () => {
     expect(h.git.push).not.toHaveBeenCalled();
   });
 
-  it('an already up-to-date merge pushes nothing but still returns the refreshed detail', async () => {
-    const h = harness({ merge: { kind: 'clean', alreadyUpToDate: true } });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+  it('an already up-to-date merge with nothing unpushed pushes nothing', async () => {
+    const h = harness({
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      unpushed: false,
+      headAfterMerge: HEAD,
+    });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: [],
+    });
     expect(h.git.push).not.toHaveBeenCalled();
     expect(h.prs.invalidateDetailCache).toHaveBeenCalledWith(7);
   });
 
+  it('retries a push that failed last time, even though this merge has nothing to do', async () => {
+    // The loop this ticket closes. An earlier update merged the target in and
+    // its push failed, so the merge is sitting in the clone. This update's
+    // merge is therefore ALREADY up to date — and the old gate, which pushed
+    // only when the merge authored a commit, skipped the push and left the
+    // request behind on the remote for the next open to find.
+    const h = harness({
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      unpushed: true,
+      publishedHead: HEAD,
+      headAfterMerge: MERGED_HEAD,
+      changedPaths: ['Sales/Deal.md'],
+    });
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.git.hasUnpushedCommits).toHaveBeenCalledWith(WS);
+    expect(h.git.push).toHaveBeenCalledWith(WS, USER);
+  });
+
+  it('falls back to "did this merge author a commit" when git cannot say what is unpushed', async () => {
+    // Never "push anyway": a push on a clone with nothing to push is a wasted
+    // round trip on every update.
+    const clean = harness({ unpushedError: new Error('git exploded') });
+    await clean.svc.updateFromTarget(WS, USER, 7);
+    expect(clean.git.push).toHaveBeenCalledWith(WS, USER);
+
+    const nothingToDo = harness({
+      unpushedError: new Error('git exploded'),
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      headAfterMerge: HEAD,
+    });
+    await nothingToDo.svc.updateFromTarget(WS, USER, 7);
+    expect(nothingToDo.git.push).not.toHaveBeenCalled();
+  });
+
   it('a rebase conflict refreshing the checkout queues recovery for the saves, then refuses', async () => {
     const conflict = new PullRebaseConflictError('alice/deal', ['Sales/Deal.md'], 'rebase stopped');
     const h = harness({ pullError: conflict });
@@ -182,15 +272,13 @@ describe('WorkflowService.updateFromTarget', () => {
 });
 
 describe('WorkflowService.updateFromTarget: the approvals the merge did not touch', () => {
-  it('carries them onto the new head, and re-reads the detail so the gate sees them', async () => {
-    const withApprovals = detail({ behind: false, headSha: MERGED_HEAD, mergeableInBevel: true });
-    const h = harness({
-      changedPaths: ['Sales/Deal.md'],
-      carried: 2,
-      withApprovals,
-    });
+  it('carries them onto the new head, before the one detail read that goes back', async () => {
+    const h = harness({ changedPaths: ['Sales/Deal.md'], carried: 2 });
 
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(withApprovals);
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: ['Sales/Deal.md'],
+    });
 
     // What moved is git's answer between the two heads — never a guess, and
     // never the request's own three-dot diff against the target.
@@ -201,23 +289,33 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
       MERGED_HEAD,
       ['Sales/Deal.md'],
     );
-    // The first refreshed detail was assembled before the rows existed, so it
-    // is not the one that goes back.
-    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(3);
   });
 
-  it('does not re-read the detail when nothing carried', async () => {
-    const h = harness({ changedPaths: ['Sales/Deal.md'], carried: 0 });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
-    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledTimes(1);
-    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(2);
+  it('answers the same list as updatedPaths — carried and re-read cannot disagree', async () => {
+    // A file whose approval was carried (so: untouched by the merge) that the
+    // dialog then re-read would be the dialog discarding content the server
+    // just called unchanged.
+    const h = harness({ changedPaths: ['Sales/Deal.md', 'Sales/Terms.md'], carried: 1 });
+    const result = await h.svc.updateFromTarget(WS, USER, 7);
+    expect(result.updatedPaths).toEqual(['Sales/Deal.md', 'Sales/Terms.md']);
+    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledWith(
+      7,
+      HEAD,
+      MERGED_HEAD,
+      result.updatedPaths,
+    );
   });
 
-  it('touches nothing when the merge had nothing to do', async () => {
-    const h = harness({ merge: { kind: 'clean', alreadyUpToDate: true } });
-    await h.svc.updateFromTarget(WS, USER, 7);
+  it('touches nothing when the head did not move', async () => {
+    const h = harness({
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      unpushed: false,
+      headAfterMerge: HEAD,
+    });
+    const result = await h.svc.updateFromTarget(WS, USER, 7);
     expect(h.git.pathsChangedBetween).not.toHaveBeenCalled();
     expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+    expect(result.updatedPaths).toEqual([]);
   });
 
   it('touches nothing when the merge conflicted — the rows describe a head that still stands', async () => {
@@ -249,10 +347,12 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
   it('falls back to the head the detail reported when that head cannot be resolved', async () => {
     // Bookkeeping never costs the update: an unresolvable ref leaves the
     // carry-forward working off the detail's head, exactly as it did before.
+    // Both resolves fail, so the head reads as unmoved from the detail's own
+    // — there is no pair of shas to diff, and the update still lands.
     const h = harness({ resolveError: new Error('no such ref'), carried: 1 });
     await h.svc.updateFromTarget(WS, USER, 7);
     expect(h.git.push).toHaveBeenCalledWith(WS, USER);
-    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledWith(7, HEAD, MERGED_HEAD, []);
+    expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
   });
 
   it('carries nothing when there is no head to compare at all', async () => {
@@ -265,7 +365,10 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
       resolveError: new Error('no such ref'),
       carried: 1,
     });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: [],
+    });
     expect(h.git.push).toHaveBeenCalledWith(WS, USER);
     expect(h.git.pathsChangedBetween).not.toHaveBeenCalled();
     expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
@@ -275,7 +378,11 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
     // A request that IS up to date is worth more than the carry-forward: the
     // approvals simply go stale, exactly as they did before this existed.
     const h = harness({ changedPathsError: new Error('git exploded') });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    const result = await h.svc.updateFromTarget(WS, USER, 7);
+    expect(result).toMatchObject({ number: 7, behind: false });
     expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+    // Which files moved is unknown, so every file the request had is named:
+    // slow beats a dialog that goes on presenting pre-merge text as current.
+    expect(result.updatedPaths).toEqual(['Sales/Deal.md']);
   });
 });

package/src/modules/workflow/agent-tools/__tests__/workflow.tools.test.ts

@@ -1,6 +1,7 @@
 import type { Server as HttpServer } from 'node:http';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
 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';
@@ -96,7 +97,7 @@ async function start(): Promise<string> {
   const toolHandler = createToolHandlerFactory(resolve);
 
   const router = express.Router();
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, 'knowledge-base');
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, testKbContext());
   router.use(createManualRoutes(registry, toolAuth));
 
   const app = express();
@@ -277,9 +278,149 @@ describe('registerWorkflowTools', () => {
     expect(calls.filter((c) => c[0] === 'createBranch')).toHaveLength(0);
   });
 
+  /**
+   * These tools address their workspace by ID — `workspaceIdForBranch(branch)`
+   * straight from the argument — so they never pass the `getFilesystem` choke
+   * point that guards the file tools. A branch-less call used to commit to a
+   * workspace id that was literally the string "undefined" — and `create_branch`
+   * used to fork from one, cloning a branch of that name and answering "There is
+   * no branch named undefined." The guard sits on the mount and is keyed on
+   * whether the tool's declared inputs REQUIRE `branch`, so it covers the
+   * injected input and a tool's own alike, without any of them remembering it.
+   */
+  describe('a branch-less call to a tool that declares `branch`', () => {
+    /**
+     * Every tool whose DECLARED inputs require `branch`, read off the mounted
+     * registry — not a list written by hand. The hand-written list is how the
+     * gap that failed Local Testing stayed invisible: it named the three tools
+     * that take the injected input and missed `create_branch`, whose `branch`
+     * is its own (the fork base) and is just as required. Anything mounted
+     * later is swept in without this file being touched.
+     */
+    const branchTakingTools = async (): Promise<string[]> =>
+      (await registryRef!.listInternal())
+        .filter((t) => {
+          const body = (t.inputs as { properties?: { body?: { required?: string[] } } }).properties?.body;
+          return (body?.required ?? []).includes('branch');
+        })
+        .map((t) => t.name);
+
+    // The inputs each tool needs BESIDES `branch`, so the only thing wrong with
+    // every call below is the missing branch.
+    const bodyFor = (tool: string): Record<string, unknown> =>
+      ({
+        commit_change: { summary: 's' },
+        save_file: { path: 'KnowledgeBase/x.md', content: 'c' },
+        create_branch: { name: 'alice/new-draft' },
+        write_file: { path: 'KnowledgeBase/x.md', content: 'c' },
+      })[tool] ?? {};
+
+    it('400s branch-required on every mounted tool that declares `branch`, and acts on nothing', async () => {
+      const base = await start();
+      const tools = await branchTakingTools();
+      // Both kinds are in here: the injected input and a tool's own required
+      // `branch`. `create_branch` is the one the reported bug survived on.
+      expect(tools).toContain('commit_change');
+      expect(tools).toContain('create_branch');
+      expect(tools).toContain('switch_branch');
+
+      for (const tool of tools) {
+        const res = await post(`${base}/api/agent/tools/${tool}`, writeTok(), bodyFor(tool));
+
+        expect(res.status, `${tool} must 400 on a branch-less call`).toBe(400);
+        expect(await res.json(), `${tool} must answer the shared refusal`).toEqual({
+          kind: 'branch-required',
+          error: '`branch` is required: pass the branch (draft) you are working on.',
+        });
+      }
+      // No workflow call was made at all — least of all one naming a workspace
+      // id built out of the missing value, or a branch forked from it.
+      expect(calls).toEqual([]);
+    });
+
+    /**
+     * The exact shapes Local Testing drove over MCP against `create_branch`:
+     * a missing branch answered 404 `There is no branch named undefined.`
+     * (a clone of that "branch" was attempted), an empty one 500 'Invalid
+     * workspace ID', and `["main"]` — which `encodeURIComponent` stringifies
+     * straight back to `main` — answered 200 and really created and pushed a
+     * branch off the default. All four are one refusal now.
+     */
+    it('refuses every absent shape on create_branch, and forks from nothing', async () => {
+      const base = await start();
+      const absent: Array<[string, Record<string, unknown>]> = [
+        ['missing', { name: 'alice/new-draft' }],
+        ['empty', { name: 'alice/new-draft', branch: '' }],
+        ['null', { name: 'alice/new-draft', branch: null }],
+        ['a number', { name: 'alice/new-draft', branch: 42 }],
+        ['an array (stringifies to a real branch name)', { name: 'alice/new-draft', branch: ['main'] }],
+        ['the literal "undefined"', { name: 'alice/new-draft', branch: 'undefined' }],
+        ['the literal "null"', { name: 'alice/new-draft', branch: 'null' }],
+      ];
+
+      for (const [label, body] of absent) {
+        const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), body);
+        expect(res.status, `branch ${label} must 400`).toBe(400);
+        const answered = await res.json();
+        expect(answered.kind, `branch ${label} must answer branch-required`).toBe('branch-required');
+        expect(JSON.stringify(answered), `branch ${label} must not echo an absent value`).not.toContain('undefined');
+      }
+      // Nothing was forked, from any workspace id.
+      expect(calls).toEqual([]);
+    });
+
+    /**
+     * `create_branch` compares `branch` (the fork base) to `name` and refuses
+     * the two being equal, QUOTING the name. A call that sent neither compared
+     * undefined to undefined, matched, and answered "not 'undefined', the draft
+     * being created" — an absent value presented as a draft name. `name` is
+     * refused by name instead, so no such sentence can be produced.
+     */
+    it('refuses a missing `name` without quoting it back', async () => {
+      const base = await start();
+
+      const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), { branch: 'main' });
+
+      expect(res.status).toBe(400);
+      const answered = await res.json();
+      expect(answered).toEqual({ kind: 'name-required', error: '`name` is required: pass the name of the draft to create.' });
+      expect(JSON.stringify(answered)).not.toContain('undefined');
+      expect(calls).toEqual([]);
+    });
+
+    it('still forks from a named base once both inputs are given', async () => {
+      const base = await start();
+      // The guards refuse absent inputs, not the tool.
+      const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), { name: 'alice/new-draft', branch: 'main' });
+
+      expect(res.status).toBe(200);
+      expect(calls).toContainEqual(['createBranch', 'main', 'alice/new-draft']);
+    });
+
+    it('refuses the stringified absent values the same way', async () => {
+      const base = await start();
+      for (const literal of ['undefined', 'null']) {
+        const res = await post(`${base}/api/agent/tools/commit_change`, writeTok(), { summary: 's', branch: literal });
+        expect(res.status, `branch "${literal}" must 400`).toBe(400);
+        expect((await res.json()).kind).toBe('branch-required');
+      }
+      expect(calls).toEqual([]);
+    });
+
+    it('leaves a tool that declares no `branch` alone', async () => {
+      const base = await start();
+      // `list_branches` is repo-global and deliberately takes no branch: the
+      // guard must not start demanding one from the tools that opted out.
+      expect((await post(`${base}/api/agent/tools/list_branches`, writeTok(), {})).status).toBe(200);
+    });
+  });
+
   it('works under a connection key too (both surface)', async () => {
     const base = await start();
-    expect((await post(`${base}/api/agent/tools/commit_change`, 'bevel_key', { summary: 's' })).status).toBe(200);
+    // `branch` is named because every caller must name it — this test is about
+    // the connection-key SURFACE, and an external key is precisely the caller
+    // that carries no focused branch to fall back on.
+    expect((await post(`${base}/api/agent/tools/commit_change`, 'bevel_key', { summary: 's', branch: WS })).status).toBe(200);
   });
 
   it('switch_branch validates + pre-warms + emits a user-scoped event (internal-only)', async () => {

package/src/modules/workflow/agent-tools/workflow.tools.ts

@@ -1,10 +1,11 @@
 import type { Router, RequestHandler } from 'express';
-import { DEFAULT_BRANCH, PROTECTED_BRANCHES } from '@bevel-software/platform-shared';
 import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
 import { ToolError, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
 import { toolDef, withBranchInput } from '../../tool-helpers/tool-def.js';
 import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { requireInternalSource } from '../../tool-auth/tool-auth.middleware.js';
+import type { KbContext } from '../../../shared/kb-context.js';
+import { assertBranchProvided } from '../../../shared/domain-errors.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
 import { RETIRED_TOOL_MESSAGES } from '@bevel-software/platform-mcp-core';
@@ -14,9 +15,10 @@ function stripKbDir(path: string, kbDirName: string): string {
   return path.startsWith(`${kbDirName}/`) ? path.slice(kbDirName.length + 1) : path;
 }
 
-// A function, not a constant: the branch model is applied during boot, and a
-// module-scope capture would freeze this at the empty set that exists before it.
-const protectedInline = () => [...PROTECTED_BRANCHES].map((b) => `\`${b}\``).join(' / ');
+// Read at call time, not captured: the branch model is applied during boot,
+// and a value taken at registration would be the empty set that exists before it.
+const protectedInline = (kb: Pick<KbContext, 'protectedBranches'>) =>
+  [...kb.protectedBranches].map((b) => `\`${b}\``).join(' / ');
 
 // Output sub-schemas for the git-aliased workflow payloads (Branch, Change,
 // ChangeRequestComment, …). Defined once and referenced by the individual tool
@@ -131,9 +133,10 @@ export function registerWorkflowTools(
   router: Router,
   toolAuth: RequestHandler,
   toolHandler: ToolHandlerFactory,
-  /** The clone folder at the workspace root; `save_file` refuses a path outside it. */
-  kbDirName: string,
+  /** The clone folder at the workspace root (`save_file` refuses a path outside it) and the branch model. */
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId' | 'protectedBranches'>,
 ): void {
+  const { kbDirName } = kb;
   const mount = (spec: {
     name: string;
     description: string;
@@ -142,16 +145,30 @@ export function registerWorkflowTools(
     write: boolean;
     /** Register on the internal catalog only (e.g. agent-control tools that make no sense to a remote caller). */
     internalOnly?: boolean;
-    /** Skip the auto-injected `branch` input — for a tool that already declares its own `branch` (switch_branch). */
+    /**
+     * Skip the auto-injected `branch` input — for a tool that declares its own
+     * `branch` with its own meaning (`create_branch`'s fork base,
+     * `switch_branch`'s target draft) or none at all (`merge_branch`,
+     * `open_change_request`, the repo-global reads). It says NOTHING about
+     * whether the tool requires a branch: that is read off the declared schema
+     * below, because reading it off this flag is what let `create_branch` opt
+     * out of the check while still demanding the input.
+     */
     skipBranch?: boolean;
     handler: ToolHandler;
   }): void => {
     const path = `/api/agent/tools/${spec.name}`;
+    const inputs = spec.skipBranch ? spec.inputs : withBranchInput(spec.inputs);
+    // The tool's OWN declaration is the only honest answer to "must this call
+    // name a branch": the injected input and a hand-declared one (the fork
+    // base, the draft to switch to) are equally required, and a tool that adds
+    // or drops the input later moves this with it.
+    const requiresBranch = ((inputs as { required?: string[] }).required ?? []).includes('branch');
     const def = toolDef({
       name: spec.name,
       description: spec.description,
       path,
-      inputs: spec.skipBranch ? spec.inputs : withBranchInput(spec.inputs),
+      inputs,
       outputs: spec.outputs,
       tags: spec.write ? ['workflow', 'write'] : ['workflow'],
     });
@@ -169,7 +186,27 @@ export function registerWorkflowTools(
       // normaliser: the root-anchored `/<kbDirName>/…` form names the same
       // workspace path, and a path with no prefix is placed under
       // `<kbDirName>/` rather than refused.
-      toolHandler((args, ctx) => spec.handler(normalizePathArgs(args, kbDirName), ctx), { write: spec.write }),
+      toolHandler(
+        (args, ctx) => {
+          // These tools hand `branch` STRAIGHT to `workspaceIdForBranch` —
+          // they address a workspace by id rather than going through
+          // `getFilesystem`, so the choke point that guards the file tools
+          // never sees them. Without this, a branch-less `commit_change`
+          // commits to a workspace id literally named "undefined", and a
+          // branch-less `create_branch` forks from one: it clones a branch of
+          // that name, fails, and answers `There is no branch named undefined.`
+          //
+          // Keyed on whether the SCHEMA requires `branch`, not on whether the
+          // input was injected. `create_branch` and `switch_branch` declare
+          // their own required `branch`; a check keyed on the injection skipped
+          // exactly those two, which is how the reported bug survived on
+          // `create_branch` — the one tool whose `branch` is a branch the
+          // caller must already have.
+          if (requiresBranch) assertBranchProvided(args.branch);
+          return spec.handler(normalizePathArgs(args, kbDirName), ctx);
+        },
+        { write: spec.write },
+      ),
     );
   };
 
@@ -180,7 +217,7 @@ export function registerWorkflowTools(
   // just to run a global op. Falls back to the default branch on a cold start
   // with no workspaces yet.
   const repoGlobalWorkspaceId = async (ctx: ToolContext): Promise<string> =>
-    (await ctx.workspaceService.findAnyWorkspaceId()) ?? workspaceIdForBranch(DEFAULT_BRANCH);
+    (await ctx.workspaceService.findAnyWorkspaceId()) ?? kb.defaultWorkspaceId();
 
   mount({
     name: 'list_branches',
@@ -303,7 +340,7 @@ export function registerWorkflowTools(
     name: 'create_branch',
     description:
       'Create a new unprotected draft named `name`, forked from the existing branch `branch`. The ' +
-      `backend rejects protected names (${protectedInline()}) and filesystem-invalid names — surface ` +
+      `backend rejects protected names (${protectedInline(kb)}) and filesystem-invalid names — surface ` +
       'those errors verbatim. Convention: `<email-localpart>/<kebab-slug>`. Does NOT switch the ' +
       'agent onto the new draft.',
     // `branch` here is the fork BASE — its own meaning — so skip the generic
@@ -328,6 +365,17 @@ export function registerWorkflowTools(
     handler: async (args, ctx: ToolContext) => {
       const name = args.name as string;
       const base = args.branch as string;
+      // `name` is declared required too, and the same-name refusal below quotes
+      // it. With nothing enforcing it, a call that named neither input compared
+      // undefined to undefined, matched, and answered "not 'undefined', the
+      // draft being created" — an absent value presented as a draft name, the
+      // very sentence this ticket exists to stop. Refused by name instead,
+      // without echoing what was not sent.
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new ToolError('`name` is required: pass the name of the draft to create.', 400, {
+          kind: 'name-required',
+        });
+      }
       // The git op runs in the base's workspace, whose clone has the base
       // checked out — the new draft forks from its HEAD. Resolving a workspace
       // lazily clones its branch from origin, so a `branch` naming the
@@ -356,7 +404,7 @@ export function registerWorkflowTools(
       type: 'object',
       properties: {
         sourceBranch: { type: 'string', minLength: 1, description: 'The draft branch carrying the changes.' },
-        targetBranch: { type: 'string', minLength: 1, description: `The branch to apply to (e.g. '${DEFAULT_BRANCH}').` },
+        targetBranch: { type: 'string', minLength: 1, description: `The branch to apply to (e.g. '${kb.defaultBranch}').` },
         title: { type: 'string', minLength: 1, maxLength: 256, description: 'Short imperative title (≤256 chars).' },
         description: { type: 'string', description: 'Optional markdown body shown verbatim to reviewers.' },
       },