@bevel-software/platform-core-backend 0.21.0 → 0.23.0

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

@@ -9,11 +9,76 @@ import { createToolContextResolver } from '../../../tool-helpers/tool-context.js
 import { createToolHandlerFactory } from '../../../tool-helpers/tool-handler.js';
 import { createManualRoutes } from '../../../tool-registry/manual.routes.js';
 import { registerWorkflowTools } from '../workflow.tools.js';
-import { OpenChangeRequestBlocksMergeError } from '../../../../shared/domain-errors.js';
+import { ChangeRequestConflictsError, OpenChangeRequestBlocksMergeError } from '../../../../shared/domain-errors.js';
 
 const WS = 'target-company-state';
 
+/**
+ * One file of a change-request detail as the service returns it: a 15 KB
+ * addition, patch included. The reported failure was 27 of these — the detail
+ * answered ~445,000 characters and overflowed the agent's tool-result limit.
+ */
+function addedFile(i: number): Record<string, unknown> {
+  const path = `KnowledgeBase/Engineering/Knowledge/Hexis/Generated-Node-${i}.md`;
+  return {
+    path,
+    status: 'added',
+    additions: 400,
+    deletions: 0,
+    // 400 × 37 characters ≈ 15 KB, as reported.
+    patch: `@@ -0,0 +1,400 @@\n${'+a line of generated knowledge text\n'.repeat(400)}`,
+    isBinary: false,
+    sha: `blob-${i}`,
+    rawUrl: `https://raw.example.com/blob-${i}`,
+  };
+}
+
+/** The per-file approval state the detail carries, as the app's dialog reads it. */
+function approvalOf(path: string): Record<string, unknown> {
+  return {
+    path,
+    eligibleApprovers: {
+      roles: ['Admin', 'Engineering'],
+      users: [{ name: 'Razvan Radulescu', email: 'razvan.radulescu@bevel.software' }],
+    },
+    approvedBy: [],
+    eligibilityResolved: true,
+    isApproved: false,
+    inMergeGate: true,
+    viewerCanApprove: true,
+  };
+}
+
+/** A full change-request detail over the given files — what `openChangeRequest` answers. */
+function detailOf(files: Record<string, unknown>[]): Record<string, unknown> {
+  return {
+    number: 7,
+    url: 'https://bevel.example.com/change-requests/7',
+    title: 'My change',
+    state: 'open',
+    branch: 'me/draft',
+    base: 'target-company-state',
+    body: 'Body shown verbatim to reviewers.',
+    author: { login: 'bevel-bot' },
+    headSha: 'head-1',
+    baseSha: 'base-1',
+    files,
+    comments: [],
+    approvals: files.map((f) => approvalOf(f.path as string)),
+    mergeableInBevel: false,
+    mergeBlockedReasons: files.map((f) => `${f.path as string} is not approved`),
+    mergeWarnings: files.map((f) => `${f.path as string} is not approved`),
+  };
+}
+
+/** The reported case: 27 new files of 15 KB each. */
+const BIG = () => detailOf(Array.from({ length: 27 }, (_, i) => addedFile(i)));
+
 let calls: unknown[][] = [];
+/** What the service answers `openChangeRequest` with; a test replaces it. */
+let opened: Record<string, unknown> = BIG();
+/** Set to make `openChangeRequest` throw instead. */
+let openFails: Error | undefined;
 const externalApiKeyService = {
   looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
   verifyAndLoadToken: async (t: string) =>
@@ -38,7 +103,8 @@ const workflowService = {
   },
   openChangeRequest: async (ws: string, user: { id: string }, body: unknown) => {
     calls.push(['openChangeRequest', ws, user.id, body]);
-    return { number: 7, url: 'https://bevel.example.com/change-requests/7' };
+    if (openFails) throw openFails;
+    return opened;
   },
   createBranch: async (ws: string, name: string) => {
     calls.push(['createBranch', ws, name]);
@@ -114,6 +180,8 @@ const post = (url: string, bearer: string, body: unknown = {}) =>
 
 beforeEach(() => {
   calls = [];
+  opened = BIG();
+  openFails = undefined;
 });
 afterEach(async () => {
   if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
@@ -229,7 +297,7 @@ describe('registerWorkflowTools', () => {
     expect(calls).toContainEqual(['listBranches', 'existing-ws']);
   });
 
-  it('open_change_request returns the CR detail', async () => {
+  it('open_change_request acts on the SOURCE branch\'s workspace', async () => {
     const base = await start();
     const res = await post(`${base}/api/agent/tools/open_change_request`, writeTok(), {
       sourceBranch: 'me/draft',
@@ -237,9 +305,6 @@ describe('registerWorkflowTools', () => {
       title: 'My change',
     });
     expect(res.status).toBe(200);
-    expect(await res.json()).toMatchObject({
-      changeRequest: { number: 7, url: 'https://bevel.example.com/change-requests/7' },
-    });
     // The workspace must be derived from the SOURCE branch (not a separate
     // `branch` arg) — encodeURIComponent('me/draft'). Regression guard for the
     // `-b undefined` clone bug when the model omitted `branch`.
@@ -251,6 +316,199 @@ describe('registerWorkflowTools', () => {
     ]);
   });
 
+  /**
+   * One test per Scenario of the Specification
+   * (`hx-change-request-answer-is-small-spec`). The reported failure: opening a
+   * request for 27 files answered ~445,000 characters, because the answer was
+   * the detail the app's dialog reads, every patch included. It overflowed the
+   * tool-result limit, so the agent could not even read the link.
+   */
+  describe('what open_change_request answers', () => {
+    const open = async (base: string, include?: string[]) => {
+      const res = await post(`${base}/api/agent/tools/open_change_request`, writeTok(), {
+        sourceBranch: 'me/draft',
+        targetBranch: 'target-company-state',
+        title: 'My change',
+        ...(include ? { include } : {}),
+      });
+      expect(res.status).toBe(200);
+      return (await res.json()) as Record<string, unknown>;
+    };
+
+    it('answers a summary for 27 new files: the link first, 25 paths of 27, approvers, blockers, no patch', async () => {
+      const base = await start();
+      const body = await open(base);
+
+      // The link is the FIRST field: the one thing the agent must hand the
+      // user, so it survives a truncation of anything after it.
+      expect(Object.keys(body)[0]).toBe('url');
+      expect(body).toMatchObject({
+        url: 'https://bevel.example.com/change-requests/7',
+        number: 7,
+        title: 'My change',
+        state: 'open',
+        sourceBranch: 'me/draft',
+        targetBranch: 'target-company-state',
+        totalFiles: 27,
+      });
+
+      const files = body.files as { path: string; change: string }[];
+      expect(files).toHaveLength(25);
+      expect(new Set(files.map((f) => f.change))).toEqual(new Set(['added']));
+      expect(files[0].path).toBe('KnowledgeBase/Engineering/Knowledge/Hexis/Generated-Node-0.md');
+
+      // Who must approve, per path — what Juan found useful and must stay.
+      expect(body.approvals).toHaveLength(25);
+      expect((body.approvals as unknown[])[0]).toEqual({
+        path: 'KnowledgeBase/Engineering/Knowledge/Hexis/Generated-Node-0.md',
+        roles: ['Admin', 'Engineering'],
+        users: ['Razvan Radulescu'],
+        approved: false,
+        inMergeGate: true,
+      });
+      // What blocks the merge: every reason, for cut paths too.
+      expect(body.mergeBlockedReasons).toHaveLength(27);
+
+      // No patch, and no file content under any other name.
+      const json = JSON.stringify(body);
+      expect(json).not.toContain('patch');
+      expect(json).not.toContain('a line of generated knowledge text');
+      expect(files.every((f) => !('patch' in f))).toBe(true);
+    });
+
+    it('keeps the 27-file answer under 10,000 characters', async () => {
+      const base = await start();
+      const body = await open(base);
+      // The detail this was shaped from is the ~445,000-character one.
+      expect(JSON.stringify(opened).length).toBeGreaterThan(400_000);
+      // 8,918 characters as this fixture stands. The three per-path lists
+      // (`files`, `approvals`, `mergeBlockedReasons`) are what fills it, so a
+      // field added to any of them eats the margin ~25 times over.
+      expect(JSON.stringify(body).length).toBeLessThan(10_000);
+    });
+
+    it('`include: ["all-paths"]` lists all 27 paths, still without patches', async () => {
+      const base = await start();
+      const body = await open(base, ['all-paths']);
+      expect(body.files).toHaveLength(27);
+      expect(body.totalFiles).toBe(27);
+      expect(body.approvals).toHaveLength(27);
+      expect(JSON.stringify(body)).not.toContain('a line of generated knowledge text');
+    });
+
+    it('`include: ["patches"]` gives each listed file its patch', async () => {
+      const base = await start();
+      const body = await open(base, ['patches']);
+      const files = body.files as { path: string; patch?: string }[];
+      expect(files).toHaveLength(25);
+      expect(files.every((f) => f.patch?.startsWith('@@ -0,0 +1,400 @@'))).toBe(true);
+      // Cut to 25 still: `patches` adds the diffs, it does not lift the cut.
+      expect(body.totalFiles).toBe(27);
+    });
+
+    it('both together: every path, each with its patch', async () => {
+      const base = await start();
+      const body = await open(base, ['patches', 'all-paths']);
+      const files = body.files as { patch?: string }[];
+      expect(files).toHaveLength(27);
+      expect(files.every((f) => typeof f.patch === 'string')).toBe(true);
+    });
+
+    it('reads a modification `changed` and a rename `moved`, with its old path', async () => {
+      const base = await start();
+      opened = detailOf([
+        { path: 'KnowledgeBase/Kept.md', status: 'modified', additions: 2, deletions: 1, patch: '@@ x', isBinary: false, sha: 'b1', rawUrl: 'r1' },
+        { path: 'KnowledgeBase/New-Home.md', previousPath: 'KnowledgeBase/Old-Home.md', status: 'renamed', additions: 0, deletions: 0, isBinary: false, sha: 'b2', rawUrl: 'r2' },
+      ]);
+      const body = await open(base);
+      expect(body.files).toEqual([
+        { path: 'KnowledgeBase/Kept.md', change: 'changed' },
+        { path: 'KnowledgeBase/New-Home.md', change: 'moved', previousPath: 'KnowledgeBase/Old-Home.md' },
+      ]);
+      expect(body.totalFiles).toBe(2);
+    });
+
+    it('a deletion reads `deleted`', async () => {
+      const base = await start();
+      opened = detailOf([
+        { path: 'KnowledgeBase/Gone.md', status: 'removed', additions: 0, deletions: 9, isBinary: false, sha: 'b3', rawUrl: 'r3' },
+      ]);
+      expect((await open(base)).files).toEqual([{ path: 'KnowledgeBase/Gone.md', change: 'deleted' }]);
+    });
+
+    it('says the approvers are unknown rather than implying nobody must approve', async () => {
+      const base = await start();
+      opened = detailOf([
+        { path: 'KnowledgeBase/Opaque.md', status: 'added', additions: 1, deletions: 0, isBinary: false, sha: 'b4', rawUrl: 'r4' },
+      ]);
+      // No usable access config on the base: the empty approver set means "not
+      // known", and nothing may be granted on the strength of that emptiness.
+      opened.approvals = [
+        { path: 'KnowledgeBase/Opaque.md', eligibleApprovers: { roles: [], users: [] }, approvedBy: [], eligibilityResolved: false, isApproved: false, inMergeGate: false },
+      ];
+      expect((await open(base)).approvals).toEqual([
+        { path: 'KnowledgeBase/Opaque.md', roles: [], users: [], approved: false, inMergeGate: false, approversUnknown: true },
+      ]);
+
+      // A detail that carries no verdict at all reads the same way: absent is
+      // not resolved, so the emptiness still means "not known".
+      const legacy = { ...(opened.approvals as Record<string, unknown>[])[0] };
+      delete legacy.eligibilityResolved;
+      opened.approvals = [legacy];
+      expect((await open(base)).approvals).toEqual([
+        { path: 'KnowledgeBase/Opaque.md', roles: [], users: [], approved: false, inMergeGate: false, approversUnknown: true },
+      ]);
+    });
+
+    it('surfaces the `change-request-conflicts` error as before', async () => {
+      const base = await start();
+      openFails = new ChangeRequestConflictsError('me/draft', 'target-company-state', ['KnowledgeBase/Clash.md']);
+      const res = await post(`${base}/api/agent/tools/open_change_request`, writeTok(), {
+        sourceBranch: 'me/draft',
+        targetBranch: 'target-company-state',
+        title: 'My change',
+      });
+      expect(res.status).toBe(409);
+      expect(await res.json()).toMatchObject({
+        kind: 'change-request-conflicts',
+        sourceBranch: 'me/draft',
+        targetBranch: 'target-company-state',
+        conflictedPaths: ['KnowledgeBase/Clash.md'],
+      });
+    });
+
+    /**
+     * The app's dialog reads the same detail from its own route. Shaping the
+     * agent's answer must not touch it — so the detail the service handed back
+     * still carries all 27 files and all their patches after the tool answered.
+     */
+    it('leaves the detail the app\'s dialog reads exactly as the service returned it', async () => {
+      const base = await start();
+      const before = JSON.stringify(opened);
+      await open(base);
+      expect(JSON.stringify(opened)).toBe(before);
+      expect((opened.files as unknown[])).toHaveLength(27);
+      expect((opened.files as { patch?: string }[]).every((f) => typeof f.patch === 'string')).toBe(true);
+    });
+
+    it('says in its description what the default answer holds and how to ask for more', async () => {
+      await start();
+      for (const tools of [await registryRef!.listInternal(), await registryRef!.listExternal()]) {
+        const def = tools.find((t) => t.name === 'open_change_request')!;
+        expect(def.description).toMatch(/SUMMARY/);
+        expect(def.description).toMatch(/cut to 25/);
+        expect(def.description).toMatch(/No patches and no file content/);
+        expect(def.description).toMatch(/include: \["patches"\]/);
+        expect(def.description).toMatch(/include: \["all-paths"\]/);
+        // `toolDef` wraps a tool's flat inputs under `body`.
+        const body = (def.inputs as { properties: { body: { properties: Record<string, { items?: { enum?: string[] }; description?: string }> } } })
+          .properties.body;
+        expect(body.properties.include.items?.enum).toEqual(['patches', 'all-paths']);
+        expect(body.properties.include.description).toMatch(/every changed path instead of the first 25/);
+      }
+    });
+  });
+
   it('create_branch forks in the BASE branch\'s workspace, never the new draft\'s', async () => {
     const base = await start();
     const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), {
@@ -278,9 +536,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/change-request-summary.ts

@@ -0,0 +1,182 @@
+import type {
+  ChangeRequestDetail,
+  ChangeRequestState,
+  ChangedFile,
+  FileApproval,
+  PrFileStatus,
+} from '@bevel-software/platform-shared';
+
+/**
+ * What `open_change_request` answers, and why it is not the detail the app's
+ * dialog reads.
+ *
+ * The dialog renders every file's diff, so its detail carries every patch. An
+ * agent that opens a change request needs none of that: it needs the link to
+ * hand the user, and enough of the request to confirm it carries the files it
+ * meant to propose and to say what the request is now waiting on. Handing it
+ * the dialog's detail cost ~445,000 characters for 27 files of 15 KB — past
+ * every tool-result limit, so the one field the agent actually needed (the
+ * link) could not be read at all.
+ *
+ * So this is a purpose-made answer: the link first, the request's identity,
+ * who must approve each path, what blocks the merge verbatim from the detail,
+ * and the changed paths with their kind of change — no patch, no file content.
+ * An agent that wants more asks for it by name through `include`.
+ */
+
+/** What `include` accepts. */
+export type ChangeRequestInclude = 'patches' | 'all-paths';
+
+/** The two `include` values, for the tool's input schema and its validation. */
+export const CHANGE_REQUEST_INCLUDES: readonly ChangeRequestInclude[] = ['patches', 'all-paths'];
+
+/** How many paths the answer lists before it cuts; `all-paths` lifts the cut. */
+export const CHANGE_REQUEST_PATH_LIMIT = 25;
+
+/**
+ * The kind of change to one path, in the four words the answer speaks. Git's
+ * own statuses are finer (`modified` vs `changed`, `renamed` vs `copied`) in
+ * ways nothing downstream acts on.
+ */
+export type ChangeKind = 'added' | 'changed' | 'deleted' | 'moved';
+
+/** One changed path. `previousPath` is where a `moved` one came from. */
+export interface ChangeRequestSummaryFile {
+  path: string;
+  change: ChangeKind;
+  previousPath?: string;
+  /** Unified diff. Only with `include: ["patches"]`, and absent for a binary or oversized file. */
+  patch?: string;
+}
+
+/**
+ * Who must approve one path, at the same per-path granularity the detail
+ * carries (the access tree resolves a role per file or per folder; this says
+ * what it resolved to for this file).
+ *
+ * The detail's own entry is the dialog's: it also carries each approver's
+ * email, the viewer's own eligibility, and every approval's timestamp and
+ * staleness. Repeated over 25 files that is ~4,500 characters an agent cannot
+ * act on — it may not approve anything — and it is what would push the
+ * 27-file answer back over the limit this ticket exists to get under. So the
+ * answer keeps what "who must approve" means and nothing else.
+ */
+export interface ChangeRequestApprovers {
+  path: string;
+  /** Roles that confer approval here. `everyone` means any signed-in approver. */
+  roles: string[];
+  /** Approvers named directly, by display name. */
+  users: string[];
+  /** True once an eligible approver has approved at the request's current head. */
+  approved: boolean;
+  /** False when the merge gate does not bind this path — then nobody has to approve it. */
+  inMergeGate: boolean;
+  /**
+   * Present when the access tree could not be resolved for this path — which
+   * includes a detail that carries no verdict at all. Then empty
+   * `roles`/`users` means "not known", NOT "nobody has to approve".
+   */
+  approversUnknown?: true;
+}
+
+export interface ChangeRequestSummary {
+  /** First field on purpose: it is the one an agent must hand the user. */
+  url: string;
+  urlNote?: string;
+  number: number;
+  title: string;
+  state: ChangeRequestState;
+  sourceBranch: string;
+  targetBranch: string;
+  /** Who must approve, one entry per listed path. */
+  approvals: ChangeRequestApprovers[];
+  /** What blocks the merge — verbatim from the detail. Empty when nothing does. */
+  mergeBlockedReasons: string[];
+  /** The changed paths, cut to {@link CHANGE_REQUEST_PATH_LIMIT} unless `all-paths` was asked for. */
+  files: ChangeRequestSummaryFile[];
+  /** How many files the request changes in total, cut or not. */
+  totalFiles: number;
+}
+
+/**
+ * A copy and a rename both carry `previousPath`, and the one thing a reader
+ * does with either is look at where the text came from — so both read `moved`.
+ * `unchanged` is a file the request lists without changing (git reports it on
+ * a mode-only change); `changed` is the honest word for it among these four.
+ */
+function changeKindOf(status: PrFileStatus | undefined): ChangeKind {
+  switch (status) {
+    case 'added':
+      return 'added';
+    case 'removed':
+      return 'deleted';
+    case 'renamed':
+    case 'copied':
+      return 'moved';
+    default:
+      return 'changed';
+  }
+}
+
+function approversOf(approval: FileApproval): ChangeRequestApprovers {
+  const eligible = approval.eligibleApprovers ?? { roles: [], users: [] };
+  return {
+    path: approval.path,
+    roles: eligible.roles ?? [],
+    users: (eligible.users ?? []).map((u) => u.name),
+    approved: approval.isApproved,
+    inMergeGate: approval.inMergeGate,
+    // Anything but an explicit `true` is unresolved — a detail built before
+    // the flag existed carries no flag at all, and reading that as "resolved"
+    // would turn an empty approver set into "nobody must approve". Same
+    // fail-closed reading as `computeViewerCanUpdate`.
+    ...(approval.eligibilityResolved !== true ? { approversUnknown: true as const } : {}),
+  };
+}
+
+function summaryFileOf(file: ChangedFile, withPatch: boolean): ChangeRequestSummaryFile {
+  return {
+    path: file.path,
+    change: changeKindOf(file.status),
+    ...(file.previousPath ? { previousPath: file.previousPath } : {}),
+    ...(withPatch && file.patch ? { patch: file.patch } : {}),
+  };
+}
+
+/**
+ * Shape the tool's answer out of the detail the service already returns. Pure:
+ * the service and the app's routes are untouched, and the detail they serve is
+ * exactly what it was.
+ *
+ * `approvals` is narrowed to the paths the answer lists, because the detail's
+ * contract is one entry per listed file. Nothing about the merge gate is lost
+ * by that: `mergeBlockedReasons` names every missing approval, cut or not.
+ */
+export function summarizeChangeRequest(
+  detail: ChangeRequestDetail,
+  include: readonly ChangeRequestInclude[] = [],
+): ChangeRequestSummary {
+  const all = detail.files ?? [];
+  const withPatch = include.includes('patches');
+  const listed = include.includes('all-paths') ? all : all.slice(0, CHANGE_REQUEST_PATH_LIMIT);
+  const listedPaths = new Set(listed.map((f) => f.path));
+  return {
+    url: detail.url,
+    ...(detail.urlNote ? { urlNote: detail.urlNote } : {}),
+    number: detail.number,
+    title: detail.title,
+    state: detail.state,
+    sourceBranch: detail.branch,
+    targetBranch: detail.base,
+    approvals: (detail.approvals ?? []).filter((a) => listedPaths.has(a.path)).map(approversOf),
+    mergeBlockedReasons: detail.mergeBlockedReasons ?? [],
+    files: listed.map((f) => summaryFileOf(f, withPatch)),
+    totalFiles: all.length,
+  };
+}
+
+/** The `include` values off a tool call's arguments; anything else is ignored. */
+export function parseInclude(raw: unknown): ChangeRequestInclude[] {
+  if (!Array.isArray(raw)) return [];
+  return CHANGE_REQUEST_INCLUDES.filter((v) => raw.includes(v));
+}