@bevel-software/platform-core-backend 0.22.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(), {

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));
+}

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

@@ -9,6 +9,12 @@ 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';
+import {
+  CHANGE_REQUEST_INCLUDES,
+  CHANGE_REQUEST_PATH_LIMIT,
+  parseInclude,
+  summarizeChangeRequest,
+} from './change-request-summary.js';
 
 /** `knowledge-base/KnowledgeBase/x.md` → `KnowledgeBase/x.md`; anything else unchanged. */
 function stripKbDir(path: string, kbDirName: string): string {
@@ -47,20 +53,31 @@ const commitSchema: JsonSchema = {
   required: ['authorName', 'authorEmail', 'sha', 'subject', 'committedAt'],
 };
 
-const changeRequestFileSchema: JsonSchema = {
+const changeRequestSummaryFileSchema: JsonSchema = {
   type: 'object',
   properties: {
     path: { type: 'string' },
-    previousPath: { type: 'string', description: 'Set for renames/copies.' },
-    status: { type: 'string', description: '`added` | `modified` | `removed` | `renamed` | `copied` | `changed` | `unchanged`.' },
-    additions: { type: 'integer' },
-    deletions: { type: 'integer' },
-    patch: { type: 'string', description: 'Unified diff; absent for binary or oversized files.' },
-    isBinary: { type: 'boolean' },
-    sha: { type: 'string', description: 'Blob SHA at the change-request head.' },
-    rawUrl: { type: 'string' },
+    change: { type: 'string', description: '`added` | `changed` | `deleted` | `moved`.' },
+    previousPath: { type: 'string', description: 'Where a `moved` file came from.' },
+    patch: {
+      type: 'string',
+      description: 'Unified diff. Only with `include: ["patches"]`, and absent for a binary or oversized file.',
+    },
+  },
+  required: ['path', 'change'],
+};
+
+const changeRequestApproversSchema: JsonSchema = {
+  type: 'object',
+  properties: {
+    path: { type: 'string' },
+    roles: { type: 'array', items: { type: 'string' }, description: 'Roles that confer approval here; `everyone` means any signed-in approver.' },
+    users: { type: 'array', items: { type: 'string' }, description: 'Approvers named directly, by display name.' },
+    approved: { type: 'boolean', description: 'True once an eligible approver has approved at the current head.' },
+    inMergeGate: { type: 'boolean', description: 'False when the merge gate does not bind this path — then nobody has to approve it.' },
+    approversUnknown: { type: 'boolean', description: 'Present when the access tree could not be resolved: empty `roles`/`users` means unknown, not nobody.' },
   },
-  required: ['path', 'status', 'additions', 'deletions', 'isBinary', 'sha', 'rawUrl'],
+  required: ['path', 'roles', 'users', 'approved', 'inMergeGate'],
 };
 
 const commentSchema: JsonSchema = {
@@ -99,24 +116,43 @@ function linkOf(cr: { number: number; url: string; urlNote?: string }): { number
   return { number: cr.number, url: cr.url, ...(cr.urlNote ? { urlNote: cr.urlNote } : {}) };
 }
 
-const changeRequestDetailSchema: JsonSchema = {
+/**
+ * What `open_change_request` answers: a summary, `url` first, with no patch and
+ * no file content. The app's dialog reads the full detail from its own route;
+ * handing that to an agent cost ~445,000 characters for 27 files of 15 KB and
+ * overflowed every tool-result limit. Built by `summarizeChangeRequest`.
+ *
+ * Property order is the answer's field order, and `url` leads it: the link is
+ * the one field the agent must hand the user, so it must survive any truncation.
+ */
+const changeRequestSummarySchema: JsonSchema = {
   type: 'object',
-  description: 'Full change-request detail (aliased from the underlying pull request).',
   properties: {
-    number: { type: 'integer' },
     url: changeRequestUrlSchema,
     urlNote: changeRequestUrlNoteSchema,
+    number: { type: 'integer' },
     title: { type: 'string' },
-    body: { type: 'string' },
-    author: { type: 'object', properties: { login: { type: 'string' }, name: { type: 'string' } }, required: ['login'] },
-    headSha: { type: 'string' },
-    baseSha: { type: 'string' },
-    files: { type: 'array', items: changeRequestFileSchema },
-    comments: { type: 'array', items: commentSchema },
-    approvals: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Per-file approval state, one entry per file in `files`.' },
+    state: { type: 'string', description: '`open` | `merged` | `closed`.' },
+    sourceBranch: { type: 'string', description: 'The draft branch carrying the changes.' },
+    targetBranch: { type: 'string', description: 'The branch the changes apply to.' },
+    approvals: {
+      type: 'array',
+      items: changeRequestApproversSchema,
+      description: 'Who must approve, one entry per listed file. A file nobody can approve (`inMergeGate: false`) blocks nothing.',
+    },
+    mergeBlockedReasons: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'What blocks the merge — every missing approval, whether its file is listed or cut. Empty when nothing blocks.',
+    },
+    files: {
+      type: 'array',
+      items: changeRequestSummaryFileSchema,
+      description: `The changed paths with their kind of change, cut to ${CHANGE_REQUEST_PATH_LIMIT}; \`include: ["all-paths"]\` lists them all.`,
+    },
+    totalFiles: { type: 'integer', description: 'How many files the request changes in total, cut or not.' },
   },
-  required: ['number', 'url', 'title', 'body', 'headSha', 'baseSha', 'files', 'comments', 'approvals'],
-  additionalProperties: true,
+  required: ['url', 'number', 'title', 'state', 'sourceBranch', 'targetBranch', 'approvals', 'mergeBlockedReasons', 'files', 'totalFiles'],
 };
 
 /**
@@ -399,6 +435,12 @@ export function registerWorkflowTools(
       'Open a change request from a draft branch into a target branch. Auto-merges the latest target ' +
       'into the source first, pushes, then creates the CR. On conflicts returns a ' +
       '`change-request-conflicts` error with affected paths. The author marker is injected server-side. ' +
+      'Answers a SUMMARY, not the request\'s content: `url` first (hand it to the user), then `number`, ' +
+      '`title`, `state`, `sourceBranch`, `targetBranch`, `approvals` (who must approve each file), ' +
+      '`mergeBlockedReasons` (what blocks the merge), and `files` — the changed paths with their kind of ' +
+      `change (\`added\` / \`changed\` / \`deleted\` / \`moved\`), cut to ${CHANGE_REQUEST_PATH_LIMIT} of \`totalFiles\`. ` +
+      'No patches and no file content: ask for the diffs with `include: ["patches"]` and for every path ' +
+      'with `include: ["all-paths"]`. ' +
       'An agent proposes; a person reviews and merges the request in the app — hand the user its `url`.',
     inputs: {
       type: 'object',
@@ -407,28 +449,37 @@ export function registerWorkflowTools(
         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.' },
+        include: {
+          type: 'array',
+          items: { type: 'string', enum: [...CHANGE_REQUEST_INCLUDES] },
+          description:
+            'Add to the default answer, which carries neither: `patches` gives each listed file its unified diff, ' +
+            `\`all-paths\` lists every changed path instead of the first ${CHANGE_REQUEST_PATH_LIMIT}. Both may be given. ` +
+            'Patches of a large request run to hundreds of thousands of characters — ask for them only when you will read them.',
+        },
       },
       required: ['sourceBranch', 'targetBranch', 'title'],
       additionalProperties: false,
     },
-    outputs: {
-      type: 'object',
-      properties: { changeRequest: changeRequestDetailSchema },
-      required: ['changeRequest'],
-    },
+    outputs: changeRequestSummarySchema,
     write: true,
     // The workspace this acts on is the SOURCE draft's — `sourceBranch` already
     // names it, so skip the auto-injected (and here redundant) `branch` input
     // rather than asking the model for both and reading the wrong one.
     skipBranch: true,
-    handler: async (args, ctx: ToolContext) => ({
-      changeRequest: await ctx.workflowService.openChangeRequest(workspaceIdForBranch(args.sourceBranch as string), ctx.user, {
-        sourceBranch: args.sourceBranch as string,
-        targetBranch: args.targetBranch as string,
-        title: args.title as string,
-        description: typeof args.description === 'string' ? args.description : undefined,
-      }),
-    }),
+    // The service still returns the full detail — the app's routes serve the
+    // same call and must keep getting it. The shaping happens here, in the
+    // answer, so nothing below the tool changes.
+    handler: async (args, ctx: ToolContext) =>
+      summarizeChangeRequest(
+        await ctx.workflowService.openChangeRequest(workspaceIdForBranch(args.sourceBranch as string), ctx.user, {
+          sourceBranch: args.sourceBranch as string,
+          targetBranch: args.targetBranch as string,
+          title: args.title as string,
+          description: typeof args.description === 'string' ? args.description : undefined,
+        }),
+        parseInclude(args.include),
+      ),
   });
 
   mount({