@bevel-software/platform-core-backend 0.25.0 → 0.26.0

package/src/modules/workflow/workflow.routes.ts

@@ -52,8 +52,13 @@ function toHttpError(
   return { status: 500, body: { error: 'Internal server error' } };
 }
 
-/** What a viewer who cannot read every touched file reads in place of a refusal's reason. */
-export const APPLY_FAILURE_REASON_WITHHELD = 'The reason names files you do not have access to read.';
+/**
+ * What a viewer who cannot read every touched file reads in place of a
+ * refusal's reason — one string, shared with the agent read tools, which
+ * withhold on the same predicate.
+ */
+export { APPLY_FAILURE_REASON_WITHHELD } from './agent-tools/change-request-read-shape.js';
+import { APPLY_FAILURE_REASON_WITHHELD } from './agent-tools/change-request-read-shape.js';
 
 function parsePrNumber(raw: string): number | null {
   if (!/^\d+$/.test(raw)) return null;

package/src/modules/workflow/workflow.service.ts

@@ -1730,6 +1730,13 @@ export class WorkflowService implements IWorkflowService {
     return this.prs.listOpenPrs(opts);
   }
 
+  listChangeRequestsByState(
+    states: ChangeRequestState[],
+    opts?: { fresh?: boolean; workspaceId?: string },
+  ): Promise<ChangeRequest[]> {
+    return this.prs.listPrsByState(states, opts);
+  }
+
   listChangeRequestsAuthoredBy(
     emailOrLogin: string,
     opts?: { fresh?: boolean },

package/src/modules/workspace/__tests__/escape-sequences.routes.test.ts

@@ -21,7 +21,8 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import { createMcpRoutes } from '../../mcp/mcp.routes.js';
 import { McpService } from '../../mcp/mcp.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { sharedFileRules, sharedFileRulesSection, sharedRulesPointer } from '../../agent-instructions/shared-file-rules.js';
+import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
 
 /**
  * Who decodes escape sequences in written content a second time — settled on
@@ -386,9 +387,9 @@ describe('what the write tools tell an agent about escape sequences', () => {
       .filter(([, d]) => d.includes('decode escape sequences in arguments before sending') || d.includes('some clients decode them in arguments'))
       .map(([n]) => n);
     expect(carrying).toEqual([]);
-    // Each of the three still points at where the warning is.
+    // Each of the three still opens by sending the agent to the guide, where the warning is.
     for (const name of ['write_file', 'write_files', 'edit_file']) {
-      expect(served[name], name).toContain(sharedRulesPointer(testKbContext().layout).trim());
+      expect(served[name]!.startsWith(GUIDE_FIRST_SENTENCE), name).toBe(true);
     }
   });
 });

package/src/modules/workspace/__tests__/workspace.routes.move-platform-files.test.ts

@@ -136,14 +136,14 @@ describe('a platform file stays in its folder', () => {
     await fs.rm(h.workspaceDir, { recursive: true, force: true });
   });
 
-  // Each of the four, at a place the platform reads it from. `access.md` and
-  // `.bevelignore` are read wherever they sit; `roles.yaml` and `AGENTS.md`
-  // are read from the repository root only.
+  // Each of the three, at a place the platform reads it from. `access.md` and
+  // `.bevelignore` are read wherever they sit; `roles.yaml` is read from the
+  // repository root only. (`AGENTS.md` is not among them: the agent guide is
+  // served from code, so a root `AGENTS.md` is the organisation's own page.)
   const PLATFORM_FILES = [
     { name: 'access.md', at: `${KB}/Sales/access.md` },
     { name: '.bevelignore', at: `${KB}/Sales/.bevelignore` },
     { name: 'roles.yaml', at: `${KB}/roles.yaml` },
-    { name: 'AGENTS.md', at: `${KB}/AGENTS.md` },
   ];
 
   it.each(PLATFORM_FILES)('refuses a rename of $name with the sentence', async ({ name, at }) => {
@@ -188,13 +188,12 @@ describe('a platform file stays in its folder', () => {
     },
   );
 
-  // The recovery move, for each of the four, from the place a misplaced copy
+  // The recovery move, for each of the three, from the place a misplaced copy
   // is actually found to the place the platform reads it.
   const RESTORES = [
     { name: 'access.md', from: `${KB}/Misplaced/access.md`, to: `${KB}/access.md`, dest: 'access.md' },
     { name: '.bevelignore', from: `${KB}/Misplaced/.bevelignore`, to: `${KB}/.bevelignore`, dest: '.bevelignore' },
     { name: 'roles.yaml', from: `${KB}/Misplaced/roles.yaml`, to: `${KB}/roles.yaml`, dest: 'roles.yaml' },
-    { name: 'AGENTS.md', from: `${KB}/Misplaced/AGENTS.md`, to: `${KB}/AGENTS.md`, dest: 'AGENTS.md' },
   ];
 
   it.each(RESTORES)(
@@ -265,6 +264,14 @@ describe('a platform file stays in its folder', () => {
 
     expect(h.moveEntry).not.toHaveBeenCalled();
     expect(h.acquireLock).not.toHaveBeenCalled();
+
+    // A root `AGENTS.md` is NOT a platform file any more — the guide is served
+    // from code — so a note renamed to it is an ordinary move that lands.
+    const guide = await move(h, `${KB}/Sales/deal.md`, `${KB}/AGENTS.md`);
+    expect(guide.status).toBe(200);
+    expect(guide.body).toEqual({ status: 'moved' });
+    expect(h.moveEntry).toHaveBeenCalledTimes(1);
+    expect(h.moveEntry).toHaveBeenCalledWith(WORKSPACE_ID, `${KB}/Sales/deal.md`, `${KB}/AGENTS.md`);
   });
 
   it('a destination that fills up after the access check is caught under the lock', async () => {
@@ -318,11 +325,15 @@ describe('a platform file stays in its folder', () => {
     }
   });
 
-  it('a nested roles.yaml or AGENTS.md is ordinary content and moves freely', async () => {
-    // They are read from the root and nowhere else, so a nested file of
-    // either name carries no platform meaning to protect.
+  it('a nested roles.yaml, and an AGENTS.md anywhere, are ordinary content and move freely', async () => {
+    // `roles.yaml` is read from the root and nowhere else, so a nested file
+    // of that name carries no platform meaning to protect. An `AGENTS.md` is
+    // never read as configuration: the platform's guide is served from code,
+    // so the organisation's own file moves and renames like any page, at the
+    // root included.
     expect((await move(h, `${KB}/Sales/roles.yaml`, `${KB}/Sales/old-roles.yaml`)).status).toBe(200);
     expect((await move(h, `${KB}/Sales/AGENTS.md`, `${KB}/Legal/AGENTS.md`)).status).toBe(200);
-    expect(h.moveEntry).toHaveBeenCalledTimes(2);
+    expect((await move(h, `${KB}/AGENTS.md`, `${KB}/Handbook/AGENTS.md`)).status).toBe(200);
+    expect(h.moveEntry).toHaveBeenCalledTimes(3);
   });
 });

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -14,19 +15,18 @@ import { SpillStore } from '../spill-store.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { registerWorkspaceTools } from '../workspace.tools.js';
-import { sharedFileRulesSection, sharedRulesPointer } from '../../agent-instructions/shared-file-rules.js';
+import { sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
 
 /**
- * What the platform TELLS AN AGENT about the conventions file, under the
- * default name and under a deployment's own.
+ * What the platform TELLS AN AGENT about the guide.
  *
- * The conventions reminder and the platform-file list are SHARED RULES now —
- * stated in the handshake instructions and in the managed agent guide, once
- * each — so their wording is asserted against that one text. What each tool
- * description still has to get right is the POINTER at the end, which names the
- * guide by the name this deployment gave it; that is the only place a remote
- * agent learns which file to open, and it has no checkout, so no harness reads
- * that file for it.
+ * The conventions reminder and the platform-file list are SHARED RULES —
+ * stated in the handshake instructions and in the guide, once each — so their
+ * wording is asserted against that one text. What each tool description has
+ * to get right is its OPENING: the one sentence saying to call
+ * `get_agent_guide` first, which the catalog puts at the front of every tool
+ * (see tool-registry/guide-first.ts); a remote agent has no checkout, so that
+ * sentence and the rule are the only places it learns what to read first.
  */
 const KB_DIR = 'knowledge-base';
 /** The context the tools read; a case applies a deployment's own names to it. */
@@ -64,70 +64,48 @@ async function listed(registry: ToolRegistry): Promise<Map<string, string>> {
 
 afterEach(() => kb.applyLayout({ ...DEFAULT_KB_LAYOUT }));
 
-describe("what names the guide, under the default name and under a deployment's own", () => {
-  it('names AGENTS.md, and CLAUDE.md beside it, under the default name', () => {
+describe('what tells an agent to read the guide first', () => {
+  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with the same guide after the organisation\'s own', () => {
     const rules = sharedFileRulesSection(kb.layout);
-    expect(rules).toContain(
-      'read `AGENTS.md` at the KB root — or `CLAUDE.md` on a knowledge base seeded before it was renamed',
-    );
+    expect(rules).toContain("call `get_agent_guide` and read the platform's guide");
+    expect(rules).toContain('read_file on `AGENTS.md` at the KB root answers with the same guide');
+    expect(rules).toContain("after the organisation's own conventions file of that name");
+    expect(rules).toContain('`CLAUDE.md`');
+    // One name on every deployment: the rule names no other.
+    expect(rules).not.toContain('HEXIS.md');
   });
 
-  it("points every entrypoint at the section, by the guide's own name", async () => {
+  it('opens every entrypoint with the guide-first sentence, reads included', async () => {
     const byName = await descriptions();
-    // On EVERY entrypoint, reads included: any of them can be a session's first.
-    for (const name of ['grep', 'list_files', 'file_stat', 'write_file', 'move_file']) {
-      expect(byName.get(name), name).toContain('see "Working with files" in AGENTS.md.');
+    for (const name of ['grep', 'list_files', 'file_stat', 'read_file', 'write_file', 'move_file', 'start_session']) {
+      expect(byName.get(name)!.startsWith(`${GUIDE_FIRST_SENTENCE} `), name).toBe(true);
+      // Once, at the front — never again further down.
+      expect(byName.get(name)!.split(GUIDE_FIRST_SENTENCE), name).toHaveLength(2);
     }
   });
 
-  it("names the configured file first and the organisation's own AGENTS.md second", () => {
-    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    const note = sharedFileRulesSection(kb.layout);
-    expect(note).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
-    expect(note).toContain("the organisation's own conventions");
-    // Ours first: an agent that reads only one must read the platform's.
-    expect(note.indexOf('`HEXIS.md`')).toBeLessThan(note.indexOf('`AGENTS.md`'));
-    // The legacy name is still offered, for a KB seeded before the rename.
-    expect(note).toContain('`CLAUDE.md`');
-  });
-
-  it('lists the platform files under the configured name, and no longer under AGENTS.md', () => {
+  it('lists the guide under no name as a platform file, and ignores a name a deployment saved for it', () => {
     kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const rules = sharedFileRulesSection(kb.layout);
-    // Listed with the depth each one counts at — `access.md` and
-    // `.bevelignore` govern the folder they sit in, the other two are read from
-    // the root — because the names alone would have an agent refuse a nested
-    // `HEXIS.md` it may rename.
-    expect(rules).toContain('`access.md` or `.bevelignore` in any folder, `roles.yaml` or `HEXIS.md` at the repository root');
-    // The customer's file is content on such a deployment, so the rule that
-    // refuses a move must not claim it.
-    expect(rules.replace(/`AGENTS\.md` if it also exists/g, '')).not.toContain('`AGENTS.md`');
-  });
-
-  it('keeps naming AGENTS.md as a platform file under the default name', () => {
-    expect(sharedFileRulesSection(kb.layout)).toContain(
-      '`access.md` or `.bevelignore` in any folder, `roles.yaml` or `AGENTS.md` at the repository root',
-    );
+    expect(rules).toContain('`access.md` or `.bevelignore` in any folder, `roles.yaml` at the repository root');
+    expect(rules).not.toContain('HEXIS.md');
+    expect(rules).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
   });
 
   /**
    * First-run setup on a fresh deployment: the tools are mounted at boot, under
    * the defaults, and the save that COMPLETES setup applies the admin's names
-   * in that same request — without a restart, deliberately, so the KB phase it
-   * runs next scaffolds the names they chose. A catalog built once at boot
-   * would go on naming `AGENTS.md` to every agent that connected afterwards.
+   * in that same request — without a restart. Nothing in the opening sentence
+   * moves with a name, so what the catalog said at boot is what it says after.
    */
-  it('follows a layout applied after the tools were mounted', async () => {
+  it('says the same thing after a layout is applied as it did at the mount', async () => {
     const registry = new ToolRegistry();
     const atMount = await descriptions(registry);
-    expect(atMount.get('grep')).toContain('in AGENTS.md.');
-
-    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' });
     const now = await listed(registry);
     for (const name of ['grep', 'file_stat', 'delete_file', 'move_file']) {
-      expect(now.get(name), name).toContain(sharedRulesPointer(kb.layout));
-      expect(now.get(name), name).not.toContain('in AGENTS.md.');
+      expect(now.get(name)!.startsWith(GUIDE_FIRST_SENTENCE), name).toBe(true);
+      expect(now.get(name), name).toBe(atMount.get(name));
     }
   });
 });