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

package/src/modules/workflow/agent-tools/change-request-read-shape.ts

@@ -22,8 +22,8 @@
  *     and an agent reading `state` should not have to read a second field to
  *     learn whether the change landed.
  *   - **One name per path.** GitHub names a pull-request file's path `filename`
- *     and a review comment's `path`; mirroring that inconsistency was the point
- *     while these tools wore GitHub's names, and is now just a trap. Every path
+ *     and elsewhere `path`; mirroring that inconsistency was the point while
+ *     these tools wore GitHub's names, and is now just a trap. Every path
  *     in every answer is `path`, and a moved file's old name is `previousPath`,
  *     as `open_change_request` names them.
  *   - **A file's kind of change** is `change` — `added` / `changed` / `deleted`
@@ -37,9 +37,6 @@
  *   - **`stale`, not `DISMISSED`.** Hexis's word for an approval a later push
  *     invalidated is `isStale`; a review entry reports `stale: true` rather
  *     than borrowing GitHub's review state.
- *   - **A reply names its parent `parentId`**, which is the argument
- *     `post_change_request_comment` takes to create one. Reading a comment and
- *     replying to it use the same word for the same thing.
  *
  * The tools' INPUTS are untouched and stay GitHub's (`state`, `head`, `base`,
  * `author`, `per_page`, `page`, `include`): the ticket pins them by name, and
@@ -53,27 +50,26 @@
  * tools file does the IO and calls in here for every decision.
  */
 
-import type {
-  ChangeRequest,
-  ChangeRequestComment,
-  ChangeRequestDetail,
-  ChangeRequestState,
-  ChangedFile,
-  FileApproval,
+import {
+  type ChangeRequest,
+  type ChangeRequestDetail,
+  type ChangeRequestState,
+  type ChangedFile,
+  type FileApproval,
 } from '@bevel-software/platform-shared';
 import { canonicalEmail, hashEmail } from '../../../shared/email-identity.js';
 import { changeKindOf, type ChangeKind } from './change-request-summary.js';
 
-/** A person on a change request, a review or a comment. */
+/** A person on a change request or a review. */
 export interface CrUser {
   /** Hexis's author login — `user-<first 12 of the email hash>`, no raw email. */
   login: string;
   /** Display name, when Hexis knows one. */
   name?: string;
   /**
-   * The person's address, for a comment author and an approver — the two
-   * places the app's own change-request surfaces already show it, and what an
-   * agent needs to address a reply to a reviewer. Never set on a change
+   * The person's address, for an approver — where the app's own
+   * change-request surfaces already show it, and what an agent needs to
+   * reach a reviewer. Never set on a change
    * request's `author`, which carries a hash-derived login only.
    */
   email?: string;
@@ -202,26 +198,6 @@ export interface CrReview {
   withheldFiles: number;
 }
 
-export interface CrComment {
-  id: string;
-  author: CrUser;
-  body: string;
-  /** Set on a file-level or inline comment. */
-  path?: string;
-  /** Set on an inline comment. */
-  line?: number;
-  /**
-   * The comment this one replies to — the same `parentId`
-   * `post_change_request_comment` takes to post the reply.
-   */
-  parentId?: string;
-  /** The head the comment was anchored to. */
-  headSha: string;
-  createdAt: string;
-  /** Present once edited. */
-  updatedAt?: string;
-}
-
 /** One page of a list, and whether there is another. */
 export interface CrPage<T> {
   items: T[];
@@ -374,7 +350,7 @@ export function toCrSummary(
   };
 }
 
-/** A detail: the row, the author's description, and the gate as this caller sees it. */
+/** A detail: the row, its description, and the gate as this caller sees it. */
 export function toCrDetail(
   detail: ChangeRequestDetail,
   counts: { readable: number; withheld: number },
@@ -388,7 +364,10 @@ export function toCrDetail(
     // read as a sha nobody can look up.
     ...(detail.headSha ? { headSha: detail.headSha } : {}),
     ...(detail.baseSha ? { baseSha: detail.baseSha } : {}),
-    body: authorsDescription(detail.body),
+    // The body is the description and nothing else — Hexis writes none of
+    // its own facts into it, so there is nothing to cut and no path in it
+    // that the author did not choose to write about.
+    body: detail.body,
     mergeable: detail.mergeableInBevel,
     mergeBlockedReasons: blockers.visible,
     withheldMergeBlockedReasons: blockers.withheld,
@@ -396,50 +375,6 @@ export function toCrDetail(
   };
 }
 
-/**
- * The part of a change-request body its AUTHOR wrote.
- *
- * A Hexis body is part human and part machine: `openChangeRequest` appends an
- * `## Affected owners` block — one line per changed path, naming that path and
- * its eligible approvers — to whatever the author typed. Returning the body
- * verbatim NAMED every file of the request, including the ones this caller may
- * not read: Local Testing caught a GTM-team reader being handed
- * `- \`KnowledgeBase/Engineering/…\` — Admin` out of a request whose file list
- * had correctly withheld that very path.
- *
- * So the generated block goes, and NOTHING ELSE does. The first cut at this
- * copied the app's dialog, which drops everything from the first `##` heading
- * on; Razvan's review (2026-10-02) asked for the narrower cut, because an
- * author who writes their description in sections loses it from that heading
- * onwards and is never told. The generated block is appended LAST and begins
- * with a line that is exactly `## Affected owners`, so cutting at the LAST such
- * line removes the machinery and keeps every heading a person wrote. (An author
- * who writes that exact heading themselves loses their text from there — the
- * safe direction, and the only way this can err.)
- *
- * Hexis's OWN hidden markers go too — the `<!--hexis:…-->` / `<!--bevel:…-->`
- * comments older bodies carry identity in — and no other comment: an HTML
- * comment the author wrote is the author's prose, like the rest.
- *
- * Who must approve each file is NOT lost by this — it is what
- * `list_change_request_files` answers under `requiredApprovers`, per file and
- * access-filtered, which is where a caller should read it from anyway.
- *
- * Two things this deliberately does not do. It does not vary by caller: one
- * body for everyone is a body nobody has to reason about. And it does not touch
- * the author's own prose, which may mention any path they chose to write about —
- * that is a person's sentence, shown to every viewer in the app, not Hexis
- * naming a file it was asked to withhold.
- */
-export function authorsDescription(body: string): string {
-  const lines = body.split('\n');
-  const generated = lines.lastIndexOf('## Affected owners');
-  return (generated === -1 ? lines : lines.slice(0, generated))
-    .join('\n')
-    .replace(/<!--\s*(?:hexis|bevel)[:/][\s\S]*?-->/g, '')
-    .trim();
-}
-
 /**
  * What this caller may do with the request.
  *
@@ -599,8 +534,7 @@ export function loginFor(email: string): string {
  * readable approvals alone, for the same reason.
  *
  * Hexis records nothing about who DECLINED a request — a rejection closes it
- * and stores no reviewer — so no review entry can report one. A reviewer's
- * objection lives in a comment, which `list_change_request_comments` returns.
+ * and stores no reviewer — so no review entry can report one.
  */
 export function toCrReviews(
   approvals: FileApproval[],
@@ -641,72 +575,3 @@ export function toCrReviews(
     withheldReviews: all.length - reviews.length,
   };
 }
-
-/** A comment. Covers the file-anchored and the general ones — Hexis has one table. */
-export function toCrComment(comment: ChangeRequestComment): CrComment {
-  return {
-    id: comment.id,
-    author: {
-      login: loginFor(comment.author.email),
-      name: comment.author.name,
-      email: comment.author.email,
-    },
-    body: comment.body,
-    ...(comment.path ? { path: comment.path } : {}),
-    ...(comment.line !== undefined ? { line: comment.line } : {}),
-    ...(comment.parentId ? { parentId: comment.parentId } : {}),
-    headSha: comment.headSha,
-    createdAt: comment.createdAt,
-    ...(comment.updatedAt ? { updatedAt: comment.updatedAt } : {}),
-  };
-}
-
-/**
- * The comments the caller may read, replies included in the answer only when
- * the comment they reply to is.
- *
- * A comment with no path is about the request as a whole, and a comment with
- * one is as readable as that path is NAMEABLE here (`mayShow`, so a comment
- * anchored to the new name of a file withheld for its old one goes with the
- * file rather than announcing it). A REPLY is neither, quite: it carries no
- * path of its own when it was posted without one, so judged on itself it is a
- * general comment — and `post_change_request_comment` takes `parentId` without
- * requiring `path`, so a reply to a comment on a withheld file was returned
- * with its body and a `parentId` naming a comment the caller cannot see.
- * Razvan's review (2026-10-02) asked for the rule the ticket states: a reply is
- * shown only when its parent is.
- *
- * So a comment is visible when its OWN path may be shown (if it has one) AND
- * its parent is visible, all the way up the chain. Both halves are needed:
- * inheriting only would show a reply naming a withheld file under a readable
- * parent, and checking only its own path would show it under a withheld one.
- *
- * Fail-closed at the edges. A `parentId` naming a comment that is not in this
- * request's list (deleted, or from somewhere this answer cannot see) is not
- * provably pathless, so the reply goes. A cycle — which the schema does not
- * permit and a corrupted row could still hold — is unresolvable, so it goes
- * too. Both are counted in the withheld total, never named.
- */
-export function visibleComments<T extends { id: string; path?: string; parentId?: string }>(
-  comments: T[],
-  mayShow: (path: string) => boolean,
-): { visible: T[]; withheld: number } {
-  const byId = new Map(comments.map((c) => [c.id, c]));
-  /** Memoised per id, so a long thread costs one walk and not one per reply. */
-  const verdicts = new Map<string, boolean>();
-  const mayShowComment = (comment: T, seen: Set<string>): boolean => {
-    const cached = verdicts.get(comment.id);
-    if (cached !== undefined) return cached;
-    if (seen.has(comment.id)) return false;
-    seen.add(comment.id);
-    let verdict = !comment.path || mayShow(comment.path);
-    if (verdict && comment.parentId) {
-      const parent = byId.get(comment.parentId);
-      verdict = parent !== undefined && mayShowComment(parent, seen);
-    }
-    verdicts.set(comment.id, verdict);
-    return verdict;
-  };
-  const visible = comments.filter((c) => mayShowComment(c, new Set()));
-  return { visible, withheld: comments.length - visible.length };
-}

package/src/modules/workflow/agent-tools/change-request-read.tools.ts

@@ -5,12 +5,11 @@ import type {
   ChangedPathPair,
   FileApproval,
 } 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 } from '../../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { IToolRegistry, JsonSchema } from '../../tool-registry/index.js';
+import { ToolError, type ToolContext, type ToolHandler, toolDef } from '../../tool-helpers/index.js';
+import type { ToolHandlerFactory } from '../../tool-helpers/index.js';
 import type { KbContext } from '../../../shared/kb-context.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { IAccessControl } from '../../access/index.js';
 import { readablePathsAt } from '../read-on-branch.js';
 import {
   PER_PAGE_DEFAULT,
@@ -23,21 +22,19 @@ import {
   pageOf,
   pagingOf,
   statesFor,
-  toCrComment,
   toCrDetail,
   toCrFile,
   toCrReviews,
   toCrSummary,
   toCrViewer,
   visibleBlockers,
-  visibleComments,
 } from './change-request-read-shape.js';
 
 /**
- * The five read tools over change requests, named and shaped after GitHub's
+ * The four read tools over change requests, named and shaped after GitHub's
  * pull-request API: `list_change_requests`, `get_change_request`,
- * `list_change_request_files`, `list_change_request_reviews` and
- * `list_change_request_comments`. The mapping lives in
+ * `list_change_request_files` and `list_change_request_reviews`. The mapping
+ * lives in
  * `change-request-read-shape.ts`; this file does the IO and the access
  * filtering.
  *
@@ -49,7 +46,7 @@ import {
  * The shape module's header says what that changed, field by field.
  *
  * None of them writes anything — every handler is registered `write: false`,
- * so a read-scoped connection key may call all five, and every service call
+ * so a read-scoped connection key may call all four, and every service call
  * below is a read.
  *
  * ## What the caller may see
@@ -58,7 +55,7 @@ import {
  * detail to any signed-in viewer; only the file CONTENT routes gate per path
  * (`canReadAtRef` at `origin/<base>`, with an unresolvable verdict as a
  * denial). These tools apply that same content gate to the whole payload,
- * because an agent's answer is the content: a file list, a reviewer's comment
+ * because an agent's answer is the content: a file list, an approval
  * and a gate warning all name paths, and an agent hands what it reads to
  * whoever it is talking to.
  *
@@ -75,11 +72,10 @@ import {
  *     answered 404 for;
  *   - files the caller may not read are left out and counted in
  *     `withheldFiles`, never named (decision 2 on the ticket);
- *   - comments on a withheld file, and gate blockers naming one, go the same
- *     way, with their own counts; a REPLY goes when the comment it replies to
- *     does, up the whole chain;
- *   - `body` is the author's own description, with the generated
- *     `## Affected owners` block cut off the end — see `authorsDescription`;
+ *   - approvals and gate blockers naming a withheld file go the same way, with
+ *     their own counts;
+ *   - `body` is the request's description, verbatim: Hexis writes nothing of
+ *     its own into it, so a path it names is one its author chose to write;
  *   - a request with no readable file and no claim of authorship answers 404,
  *     indistinguishable from a number that was never issued.
  *
@@ -172,7 +168,7 @@ export function registerChangeRequestReadTools(
     properties: {
       login: { type: 'string', description: 'Hash-derived login (`user-<12 hex>`); no raw address.' },
       name: { type: 'string' },
-      email: { type: 'string', description: 'Set for comment authors and approvers only.' },
+      email: { type: 'string', description: 'Set for approvers only.' },
     },
     required: ['login'],
   };
@@ -189,7 +185,7 @@ export function registerChangeRequestReadTools(
       sourceBranch: { type: 'string', description: 'The branch the change comes from.' },
       targetBranch: { type: 'string', description: 'The branch it would be applied to.' },
       createdAt: { type: 'string', description: 'ISO timestamp.' },
-      updatedAt: { type: 'string', description: 'ISO timestamp — the close time of a closed request, else the creation time.' },
+      updatedAt: { type: 'string', description: 'ISO timestamp — the latest of the request\'s creation time, its row `updated_at` (a title or description edit, a reopen) and its close time; approvals do not affect it.' },
       changedFiles: { type: 'integer', description: 'How many of its files YOU may read.' },
       withheldFiles: { type: 'integer', description: 'How many of its files you may not read. Never named.' },
       lastApplyFailure: {
@@ -294,7 +290,7 @@ export function registerChangeRequestReadTools(
       // move under its new name alone, so a file moved out of a folder this
       // caller cannot open looked readable here while the detail — which pairs
       // the two names — refused it: the list advertised a change request that
-      // all four by-number tools answered 404 for, and counted its withheld
+      // all three by-number tools answered 404 for, and counted its withheld
       // file as zero. One notion of a readable file, shared with the detail
       // through the same `fileIsReadable`, is what stops the two disagreeing.
       const byBase = new Map<string, string[]>();
@@ -354,7 +350,7 @@ export function registerChangeRequestReadTools(
       type: 'object',
       properties: {
         ...(changeRequestSchema as { properties: Record<string, JsonSchema> }).properties,
-        body: { type: 'string', description: "What the AUTHOR wrote. The generated `## Affected owners` block Hexis appends — which names every changed path — is cut off the end; read who must approve each file from `list_change_request_files`." },
+        body: { type: 'string', description: "The request's description, exactly as its author or a later edit left it. Who must approve each file is not in it; read that from `list_change_request_files`." },
         headSha: { type: 'string', description: 'The source commit this answer describes. Absent when no commit could be resolved.' },
         baseSha: { type: 'string', description: 'The target commit it is read against. Absent when no commit could be resolved.' },
         mergeable: { type: 'boolean', description: "Hexis's merge gate, which also waits on the per-file approvals. May be false while `mergeBlockedReasons` is empty, if a blocker names a file you may not read." },
@@ -501,9 +497,9 @@ export function registerChangeRequestReadTools(
       "List a change request's reviews (GitHub: list reviews): who approved what, and when. " +
       'Hexis approves per FILE, so each entry names a `reviewer`, the `files` they approved and ' +
       'the time of the latest of them; `stale` is true for approvals a later push invalidated. ' +
-      'Nothing records who DECLINED a request, so no entry reports one — a reviewer\'s objection ' +
-      'is a comment. Read-only: an entry keeps only the files you may read, and one with no ' +
-      'readable file at all is counted in `withheldReviews` rather than named.',
+      'Nothing records who DECLINED a request, so no entry reports one. Read-only: an entry keeps ' +
+      'only the files you may read, and one with no readable file at all is counted in ' +
+      '`withheldReviews` rather than named.',
     inputs: {
       type: 'object',
       properties: {
@@ -549,74 +545,11 @@ export function registerChangeRequestReadTools(
       return { reviews: items, withheldReviews, ...paging };
     },
   });
-
-  // ── list_change_request_comments ──────────────────────────────────────────
-
-  mount({
-    name: 'list_change_request_comments',
-    description:
-      "List a change request's comments (GitHub: list review comments and issue comments — Hexis " +
-      'keeps both in one thread). Each carries its `author`, `body`, `path` and `line` when it is ' +
-      'anchored to a file, `parentId` when it is a reply (the same id you pass to ' +
-      '`post_change_request_comment` to reply yourself), and its times. Read-only. A comment on a ' +
-      'file you may not read is left out and counted in `withheldComments`, and so is a reply to ' +
-      'a comment that was left out.',
-    inputs: {
-      type: 'object',
-      properties: {
-        number: { type: 'integer', minimum: 1, description: 'Change request number.' },
-        ...pagingInputs,
-      },
-      required: ['number'],
-      additionalProperties: false,
-    },
-    outputs: {
-      type: 'object',
-      properties: {
-        comments: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              id: { type: 'string', description: 'Pass as `parentId` to `post_change_request_comment` to reply.' },
-              author: userSchema,
-              body: { type: 'string' },
-              path: { type: 'string', description: 'Repository-relative path, on a file-level or inline comment.' },
-              line: { type: 'integer', description: 'Set on an inline comment.' },
-              parentId: { type: 'string', description: 'The comment this one replies to.' },
-              headSha: { type: 'string', description: 'The commit the comment was anchored to.' },
-              createdAt: { type: 'string', description: 'ISO timestamp.' },
-              updatedAt: { type: 'string', description: 'ISO timestamp; present once edited.' },
-            },
-            required: ['id', 'author', 'body', 'headSha', 'createdAt'],
-          },
-        },
-        withheldComments: { type: 'integer', description: 'Comments on a file you may not read, and replies to those.' },
-        ...pagingOutputs,
-      },
-      required: ['comments', 'withheldComments', ...pagingRequired],
-    },
-    handler: async (args, ctx: ToolContext) => {
-      const number = numberArg(args);
-      const { perPage, page } = pagingOf(args);
-      const scoped = await scopedDetail(ctx, number, { patches: false });
-      // A comment with no path is about the request as a whole; one with a path
-      // is as readable as that path is NAMEABLE here. A reply inherits its
-      // parent's verdict up the chain — see `visibleComments`.
-      const { visible, withheld } = visibleComments(scoped.detail.comments, scoped.mayShow);
-      const { items, ...paging } = pageOf(visible, perPage, page);
-      return {
-        comments: items.map(toCrComment),
-        withheldComments: withheld,
-        ...paging,
-      };
-    },
-  });
 }
 
 /**
  * The detail of request `number` with the access filter applied, or a 404 —
- * the one place the four by-number tools get their data, so they cannot
+ * the one place the three by-number tools get their data, so they cannot
  * drift on who may see what.
  */
 export interface ScopedDetail {
@@ -634,8 +567,8 @@ export interface ScopedDetail {
    * The two differ on exactly one shape, and it is the shape that leaks: a
    * file moved out of a folder the caller may not read is readable under
    * its NEW name, yet `fileIsReadable` withholds it whole (its diff shows the
-   * old path's content). Anything keyed on that new path — an approval, a
-   * comment anchored to it — would otherwise say the request touches a file
+   * old path's content). Anything keyed on that new path — an approval of
+   * it — would otherwise say the request touches a file
    * the file tool refuses to list, under a name it refuses to print.
    */
   mayShow: (path: string) => boolean;
@@ -686,15 +619,10 @@ export function changeRequestScope(
     });
     if (!detail) throw notFound(number);
     const viewerIsAuthor = isAuthor(detail, ctx.user.email);
-    // Comment paths join the batch: a comment may name a file the request no
-    // longer changes, and without a verdict of its own it would be withheld
-    // from a caller who can read it perfectly well.
-    const commentPaths = detail.comments.map((c) => c.path).filter((p): p is string => !!p);
     // BOTH names of every file: a move is judged on its old path as well as
     // its new one, because the diff of a move shows what was at the old one.
     const readable = await readablePaths(ctx, workspaceId, detail.base, [
       ...detail.files.flatMap(pathsOf),
-      ...commentPaths,
     ]);
     const mayRead = (path: string) => readable.has(path);
     const readableFiles = detail.files.filter((f) => fileIsReadable(f, mayRead));
@@ -703,7 +631,7 @@ export function changeRequestScope(
     }
     // Every name a withheld file goes by, so a gate warning quoting either
     // spelling is caught by the blocker filter — and so `mayShow` catches
-    // whichever spelling an approval or a comment happens to use.
+    // whichever spelling an approval happens to use.
     const withheldFilePaths = detail.files
       .filter((f) => !fileIsReadable(f, mayRead))
       .flatMap(pathsOf);

package/src/modules/workflow/agent-tools/change-request-summary.ts

@@ -65,7 +65,11 @@ export interface ChangeRequestApprovers {
   path: string;
   /** Roles that confer approval here. `everyone` means any signed-in approver. */
   roles: string[];
-  /** Approvers named directly, by display name. */
+  /**
+   * Approvers named directly: each by display name, or by email when the
+   * access tree resolved no name (an owner listed only by email has none).
+   * Never a blank string — an approver with neither is left out.
+   */
   users: string[];
   /** True once an eligible approver has approved at the request's current head. */
   approved: boolean;
@@ -129,12 +133,22 @@ export function changeKindOf(status: PrFileStatus | undefined): ChangeKind {
   }
 }
 
+/**
+ * How the answer names one approver: the display name when there is one, the
+ * email otherwise. The resolver hands back an empty name for an owner that
+ * `roles.yaml` lists by email, so the name alone left the agent `[""]` while
+ * `mergeBlockedReasons` named the same owner by email.
+ */
+function approverName(user: { name?: string; email?: string }): string {
+  return user.name?.trim() || user.email?.trim() || '';
+}
+
 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),
+    users: (eligible.users ?? []).map(approverName).filter((n) => n !== ''),
     approved: approval.isApproved,
     inMergeGate: approval.inMergeGate,
     // Anything but an explicit `true` is unresolved — a detail built before