@bevel-software/platform-core-backend 0.31.0 → 0.33.0

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;
@@ -96,6 +100,13 @@ export interface ChangeRequestSummary {
   files: ChangeRequestSummaryFile[];
   /** How many files the request changes in total, cut or not. */
   totalFiles: number;
+  /**
+   * The channels that reached the approvers as the request was opened
+   * (`['email']`, say), as the deployment's listeners said; empty when nobody
+   * was told. Only on the answer to an open — a request read later has no
+   * such moment to report.
+   */
+  notified?: string[];
 }
 
 /**
@@ -122,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
@@ -157,7 +178,7 @@ function summaryFileOf(file: ChangedFile, withPatch: boolean): ChangeRequestSumm
  * by that: `mergeBlockedReasons` names every missing approval, cut or not.
  */
 export function summarizeChangeRequest(
-  detail: ChangeRequestDetail,
+  detail: ChangeRequestDetail & { notified?: string[] },
   include: readonly ChangeRequestInclude[] = [],
 ): ChangeRequestSummary {
   const all = detail.files ?? [];
@@ -176,6 +197,8 @@ export function summarizeChangeRequest(
     mergeBlockedReasons: detail.mergeBlockedReasons ?? [],
     files: listed.map((f) => summaryFileOf(f, withPatch)),
     totalFiles: all.length,
+    // Only an open carries it; a read of a request later has none to report.
+    ...(detail.notified ? { notified: detail.notified } : {}),
   };
 }
 

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

@@ -1,16 +1,15 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
-import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
+import type { IToolRegistry, JsonSchema } from '../../tool-registry/index.js';
+import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler, toolDef } from '../../tool-helpers/index.js';
 import { isCommitSha } from '../../../shared/git.contract.js';
-import { toolDef } 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 { IAccessControl } from '../../access/access-control.interface.js';
+import type { ToolHandlerFactory } from '../../tool-helpers/index.js';
+import { requireInternalSource } from '../../tool-auth/index.js';
+import type { IAccessControl } from '../../access/index.js';
 import { assertAgentWriteAllowed, notifyAgentRead, SESSION_ID_INPUT, type AgentAccessGate } from '../../workspace/index.js';
 import { readablePathsAt, readableAtCommits, assertReadableAtCommits } from '../read-on-branch.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
+import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/index.js';
 import { RETIRED_TOOL_MESSAGES } from '@bevel-software/platform-mcp-core';
 import {
   CHANGE_REQUEST_INCLUDES,
@@ -30,7 +29,7 @@ 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
+// ChangeRequest, …). Defined once and referenced by the individual tool
 // defs below so each tool still declares its own `outputs`.
 const branchSchema: JsonSchema = {
   type: 'object',
@@ -75,7 +74,7 @@ const changeRequestApproversSchema: JsonSchema = {
   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.' },
+    users: { type: 'array', items: { type: 'string' }, description: 'Approvers named directly: each by display name, or by email when the access tree resolved no name. Never a blank string.' },
     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.' },
@@ -83,22 +82,6 @@ const changeRequestApproversSchema: JsonSchema = {
   required: ['path', 'roles', 'users', 'approved', 'inMergeGate'],
 };
 
-const commentSchema: JsonSchema = {
-  type: 'object',
-  properties: {
-    id: { type: 'string' },
-    author: { type: 'object', properties: { email: { type: 'string' }, name: { type: 'string' } }, required: ['email', 'name'] },
-    body: { type: 'string' },
-    path: { type: 'string', description: 'Set for file-level / inline comments.' },
-    line: { type: 'integer', description: 'Set for inline comments.' },
-    headSha: { type: 'string', description: 'Head the comment was anchored to.' },
-    parentId: { type: 'string', description: 'Root comment id when this is a reply.' },
-    createdAt: { type: 'string', description: 'ISO timestamp.' },
-    updatedAt: { type: 'string', description: 'ISO timestamp; present once edited.' },
-  },
-  required: ['id', 'author', 'body', 'headSha', 'createdAt'],
-};
-
 const changeRequestUrlSchema: JsonSchema = {
   type: 'string',
   description:
@@ -107,13 +90,6 @@ const changeRequestUrlSchema: JsonSchema = {
 };
 const changeRequestUrlNoteSchema: JsonSchema = { type: 'string', description: 'Present only when `url` is relative — how to get absolute links.' };
 
-/** The link to a change request, for a tool whose payload is not the change request itself. */
-const changeRequestLinkSchema: JsonSchema = {
-  type: 'object',
-  properties: { number: { type: 'integer' }, url: changeRequestUrlSchema, urlNote: changeRequestUrlNoteSchema },
-  required: ['number', 'url'],
-};
-
 /** `{ number, url, urlNote? }` of a change request summary or detail. */
 function linkOf(cr: { number: number; url: string; urlNote?: string }): { number: number; url: string; urlNote?: string } {
   return { number: cr.number, url: cr.url, ...(cr.urlNote ? { urlNote: cr.urlNote } : {}) };
@@ -154,6 +130,12 @@ const changeRequestSummarySchema: JsonSchema = {
       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.' },
+    notified: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'On the answer to an open only: the channels that reached the approvers ("email", say), as the deployment\'s listeners said; empty when nobody was told and the request waits to be found in the app.',
+    },
   },
   required: ['url', 'number', 'title', 'state', 'sourceBranch', 'targetBranch', 'approvals', 'mergeBlockedReasons', 'files', 'totalFiles'],
 };
@@ -177,7 +159,9 @@ export function registerWorkflowTools(
   /**
    * Whether the caller may see change request `number` — `get_change_request`'s
    * own gate (`changeRequestScope(...).maySee`). `delete_branch` neither names
-   * nor links a request it answers no for.
+   * nor links a request it answers no for, and `update_change_request` answers
+   * such a request exactly as `get_change_request` does (404) before reading its
+   * state or who may edit it.
    */
   maySeeChangeRequest: (ctx: ToolContext, number: number) => Promise<boolean>,
   /**
@@ -466,7 +450,7 @@ export function registerWorkflowTools(
         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. '${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.' },
+        description: { type: 'string', maxLength: 64_000, description: 'Optional markdown body shown verbatim to reviewers (≤64,000 chars).' },
         include: {
           type: 'array',
           items: { type: 'string', enum: [...CHANGE_REQUEST_INCLUDES] },
@@ -501,66 +485,62 @@ export function registerWorkflowTools(
   });
 
   mount({
-    name: 'post_change_request_comment',
+    name: 'update_change_request',
     description:
-      'Post a review comment on a change request. Three modes: general (no path), file-level (path), ' +
-      'inline (path + line). Anchors to the CR\'s current head.',
+      'Change the title and/or the description of an OPEN change request. Allowed for its author and for anyone ' +
+      'who may merge it (an admin, or someone who may approve every file it changes) — the same rule as the app\'s ' +
+      'Edit control; anyone else is refused (403), and so is a merged or closed request (409), in words. ' +
+      "`description` replaces the request's description whole — the text `get_change_request` answers as `body`; " +
+      '`appendDescription` instead adds a paragraph after the description as it stands when the write happens, so two ' +
+      'notes racing each other both land (never together with `description`). Give at least one field; an absent one keeps its text. ' +
+      '`get_change_request` answers the new text at once. A request you may not see answers 404, as `get_change_request` does.',
     inputs: {
       type: 'object',
       properties: {
         number: { type: 'integer', minimum: 1, description: 'Change request number.' },
-        body: { type: 'string', minLength: 1, description: 'Comment body (Markdown).' },
-        path: { type: 'string', description: `Repository-relative path of the changed file for a file-level/inline comment (e.g. \`KnowledgeBase/Foo.md\`); the workspace form \`${kbDirName}/KnowledgeBase/Foo.md\`, with or without a leading slash, names the same file.` },
-        line: { type: 'integer', minimum: 1, description: 'Line number for an inline comment. Requires `path`.' },
-        parentId: { type: 'string', description: 'Comment id to reply to.' },
+        title: { type: 'string', minLength: 1, maxLength: 256, description: 'The new title (≤256 chars).' },
+        description: { type: 'string', maxLength: 64_000, description: 'The new description (Markdown, ≤64,000 chars); an empty string clears it.' },
+        appendDescription: { type: 'string', maxLength: 64_000, description: 'A paragraph (Markdown) added after the description as stored at the moment of the write; what it leaves is ≤64,000 chars. Not together with `description`.' },
       },
-      required: ['number', 'body'],
+      required: ['number'],
       additionalProperties: false,
     },
     outputs: {
       type: 'object',
       properties: {
-        comment: { ...commentSchema, description: 'The posted review comment.' },
-        changeRequest: { ...changeRequestLinkSchema, description: 'The change request commented on.' },
+        number: { type: 'integer' },
+        url: changeRequestUrlSchema,
+        urlNote: changeRequestUrlNoteSchema,
+        title: { type: 'string', description: 'The title as it now stands.' },
       },
-      required: ['comment', 'changeRequest'],
+      required: ['number', 'url', 'title'],
     },
     write: true,
-    // Keyed by change-request number, not a draft — the workspace is only a
-    // scratch clone to run the repo op in, so resolve any existing one rather
-    // than requiring a `branch`.
+    // Keyed by change-request number; the service resolves the request's own
+    // base branch for the permission check.
     skipBranch: true,
     handler: async (args, ctx: ToolContext) => {
+      const title = typeof args.title === 'string' ? args.title : undefined;
+      const description = typeof args.description === 'string' ? args.description : undefined;
+      const appendDescription = typeof args.appendDescription === 'string' ? args.appendDescription : undefined;
+      if (title === undefined && description === undefined && appendDescription === undefined) {
+        throw new ToolError('Give a new `title`, a new `description`, or an `appendDescription`.', 400);
+      }
+      // A request the caller may not read is not found — never a 403 or a
+      // state-specific 409, which would tell a probe that it exists.
       const number = args.number as number;
-      const line = typeof args.line === 'number' ? args.line : undefined;
-      // A change request's files are repository-relative; the workspace form
-      // Copy path gives (`/<kbDirName>/…`, its slash already dropped by the
-      // mount) carries the clone folder, which no changed file would match.
-      const path = typeof args.path === 'string' ? stripKbDir(args.path, kbDirName) : undefined;
-      if (line !== undefined && !path) {        throw new ToolError('`path` is required when `line` is provided (inline comments anchor to a file).', 400);
+      if (!(await maySeeChangeRequest(ctx, number))) {
+        throw new ToolError(`Change request #${number} not found.`, 404);
       }
-      const detail = await ctx.workflowService.getChangeRequestDetail(number, {
-        fresh: true,
-        workspaceId: await repoGlobalWorkspaceId(ctx),
-        viewerEmail: ctx.user.email,
+      const updated = await ctx.workflowService.updateChangeRequest(number, ctx.user, {
+        title,
+        description,
+        appendDescription,
       });
-      if (!detail) {        throw new ToolError(`Change request #${number} not found.`, 404);
-      }
-      // A comment anchors to a commit, and a DECLINED request has none to anchor
-      // to: nothing durable records what it proposed, so its detail carries no
-      // head (see `changeSourceFor`). Say that, rather than letting the service's
-      // `head sha is required` surface as a 400 about an argument the caller
-      // never passed. An APPLIED request still takes comments — its head is the
-      // source tip its merge commit recorded.
-      if (!detail.headSha) {        throw new ToolError(`Change request #${number} is ${detail.state} and has no commit to anchor a comment to.`, 409);
-      }
-      const comment = await ctx.workflowService.postComment(
-        number,
-        ctx.user,
-        { body: args.body as string, path, line, parentId: typeof args.parentId === 'string' ? args.parentId : undefined },
-        detail.headSha,
-      );
-      return { comment, changeRequest: linkOf(detail) };
+      return {
+        ...linkOf(updated),
+        title: updated.title,
+      };
     },
   });
 

package/src/modules/workflow/change-request-hooks.ts

@@ -0,0 +1,96 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { ListenerSeam, type NotifyingListener } from '../../shared/listener-seam.js';
+
+const log = logger('cr');
+
+/** Somebody a listener can write to: an account's id, address and name. */
+export type ChangeRequestPerson = Pick<AuthUser, 'id' | 'email' | 'name'>;
+
+/**
+ * A change request was OPENED — by a person in the app or by an agent through
+ * its tool, which take the one road (`WorkflowService.openChangeRequest`).
+ * Raised once per request, after its row exists and its source branch was
+ * pushed, or the push was refused: the request exists either way, and the
+ * branch's next push carries the commits. Never raised for a request that is
+ * reopened after a failed branch deletion — it was opened once already — nor
+ * for one updated from its target.
+ */
+export interface ChangeRequestOpenedEvent {
+  number: number;
+  title: string;
+  sourceBranch: string;
+  targetBranch: string;
+  /** Who opened it: the person, or the person the agent acted for. */
+  openedBy: ChangeRequestPerson;
+  /**
+   * The distinct people eligible to approve some changed path, as accounts —
+   * the eligibility the request's per-file approvals show, with the
+   * roles and groups expanded to their members, each person once however
+   * many paths or roles name them. Only a person with an account is here: a
+   * listener writes to accounts. The author is not left out; a listener that
+   * will not tell people of their own request reads `openedBy`.
+   */
+  approvers: ChangeRequestPerson[];
+  /**
+   * Eligible approvers the event cannot hand over as accounts, each counted
+   * once: a person the access model names who has no account yet, and the
+   * built-in `everyone` (anyone signed in may approve, and nobody can be
+   * listed for that). Zero when every approver is in `approvers`.
+   */
+  unresolvedApprovers: number;
+  /**
+   * The request's address, when the deployment has a public address
+   * configured (`PUBLIC_FRONTEND_URL`). Absent otherwise: a listener that
+   * knows where the app is builds the link to `/change-requests/<number>`
+   * itself.
+   */
+  url?: string;
+  /**
+   * Whether the source branch's push was refused by the host as the request
+   * was opened: the request exists, but its commits reach the host only when
+   * an agent has reconciled the branch and pushed again, which is seconds
+   * usually and may fail. A listener decides what that is worth — a mail
+   * worded for it, a delay, or none — because a reviewer sent to the
+   * request before then opens one whose changes are not there yet. False
+   * when the push landed.
+   */
+  pushPending: boolean;
+}
+
+/**
+ * A listener answers how it reached the approvers — a non-empty channel name,
+ * `'email'` say — or null when it did not; the rule is {@link NotifyingListener}'s:
+ * awaited, a throw logged and counted as null, never failing the open.
+ */
+export type ChangeRequestOpenedHook = NotifyingListener<ChangeRequestOpenedEvent>;
+
+/**
+ * Core's seam for "a change request was opened": a deployment (the cloud
+ * with its mail, an enterprise overlay) registers how to tell the reviewers,
+ * and core says in its answer whether somebody did. Core registers nothing,
+ * so a core-only deployment notifies nobody and the request waits to be
+ * found in the app, as before.
+ */
+export interface IChangeRequestHooks {
+  onChangeRequestOpened(hook: ChangeRequestOpenedHook): void;
+  /** Run every listener in registration order; the channels that reached the approvers, in that order. */
+  runChangeRequestOpened(event: ChangeRequestOpenedEvent): Promise<string[]>;
+}
+
+export class ChangeRequestHooks implements IChangeRequestHooks {
+  // The request exists whether or not the reviewers were told: the opener's
+  // answer says they were not, and the request is found in the app as before.
+  private readonly opened = new ListenerSeam<ChangeRequestOpenedEvent>(
+    log,
+    'a change-request-opened listener failed; the reviewers were not notified by it:',
+  );
+
+  onChangeRequestOpened(hook: ChangeRequestOpenedHook): void {
+    this.opened.add(hook);
+  }
+
+  runChangeRequestOpened(event: ChangeRequestOpenedEvent): Promise<string[]> {
+    return this.opened.run(event);
+  }
+}

package/src/modules/workflow/event-bus.ts

@@ -179,7 +179,9 @@ export class WorkflowEventBus {
         log.warn(`dispatch to session ${sub.sessionId} threw:`, { err });
       }
     }
-    log.info(`EMIT id=${event.id} kind=${event.kind} → delivered=${matched} skipped=${skipped}`);
+    // `pushed`, not delivered: the events route's delivery rule may still
+    // withhold the event from a session it was pushed to.
+    log.info(`EMIT id=${event.id} kind=${event.kind} → pushed=${matched} skipped=${skipped}`);
     return event;
   }