@bevel-software/platform-core-backend 0.22.0 → 0.24.0

package/src/modules/agent-instructions/__tests__/shared-file-rules.test.ts

@@ -0,0 +1,238 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  DEFAULT_KB_LAYOUT,
+  LEGACY_AGENTS_FILE,
+  PREAMBLE_CAP,
+  renderKbLayoutPlaceholders,
+} from '@bevel-software/platform-shared';
+import { describe, expect, it } from 'vitest';
+import { defaultKbTemplateDir } from '../../../assets.js';
+import { renderTemplateText, SHARED_FILE_RULES_PLACEHOLDER } from '../../workspace/startup/steps/template-source.js';
+import {
+  INSTRUCTIONS_CAP,
+  PLATFORM_HEADER,
+  PREAMBLE_TRUNCATION_MARKER,
+  composeAgentInstructions,
+  platformInstructions,
+} from '../compose.js';
+import {
+  POINTER_GUIDE_NAME_BUDGET,
+  SHARED_FILE_RULES_CAP,
+  SHARED_RULES_POINTER_MAX,
+  SHARED_RULES_SECTION,
+  sharedFileRules,
+  sharedFileRulesSection,
+  sharedRulesPointer,
+} from '../shared-file-rules.js';
+
+/**
+ * The rules every file tool shares are stated in TWO places — the handshake
+ * `instructions` and the platform-managed agent guide — and in neither tool
+ * description. These tests are what makes "stated once" true: the two places
+ * carry the SAME string, built from one text, so a rule cannot be changed in one
+ * and left stale in the other.
+ */
+
+/** The packaged template's agent guide, as it ships (placeholders unrendered). */
+async function guideTemplate(): Promise<string> {
+  return readFile(path.join(defaultKbTemplateDir(), LEGACY_AGENTS_FILE), 'utf8');
+}
+
+describe('the shared file rules are one text, in two places', () => {
+  it('puts the identical section in the handshake instructions and in the managed guide', async () => {
+    const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT);
+    expect(section.startsWith(`## ${SHARED_RULES_SECTION}\n\n`)).toBe(true);
+
+    const instructions = composeAgentInstructions(null).instructions;
+    expect(instructions).toContain(section);
+
+    const guide = renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT);
+    expect(guide).toContain(section);
+
+    // Byte-for-byte the same text in both, which is the whole point: neither is
+    // a hand-written copy that could be edited on its own.
+    const inGuide = guide.slice(guide.indexOf(section), guide.indexOf(section) + section.length);
+    const inInstructions = instructions.slice(
+      instructions.indexOf(section),
+      instructions.indexOf(section) + section.length,
+    );
+    expect(inGuide).toBe(inInstructions);
+  });
+
+  it('states every rule in both places, and the content rule exactly once in each', async () => {
+    const instructions = composeAgentInstructions(null).instructions;
+    const guide = renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT);
+    const rules = sharedFileRules(DEFAULT_KB_LAYOUT);
+    expect(rules.map((r) => r.id)).toEqual([
+      'agent-guide',
+      'content-kinds',
+      'write-mode',
+      'images-in-pages',
+      'escape-sequences',
+      'upload-route',
+      'dry-run-confirm',
+      'managed-items',
+      'refused-for-permissions',
+      'tool-chain',
+    ]);
+    for (const rule of rules) {
+      expect(instructions, rule.id).toContain(rule.body);
+      expect(guide, rule.id).toContain(rule.body);
+    }
+    // Once in each, not twice: the rule used to arrive on a dozen tools at a time.
+    const contentRule = rules.find((r) => r.id === 'content-kinds')!.body.split('\n\n')[0];
+    expect(instructions.split(contentRule)).toHaveLength(2);
+    expect(guide.split(contentRule)).toHaveLength(2);
+  });
+
+  it('carries the whole content rule — the refused families, the byte tools and the upload path', async () => {
+    for (const text of [composeAgentInstructions(null).instructions, renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT)]) {
+      expect(text).toContain('`binary_not_writable`');
+      expect(text).toContain('copy_file, move_file and delete_file act on bytes of any kind');
+      expect(text).toContain('unzip extracts the entries of a `.zip`');
+      // The upload path by the names of the tools this deployment serves.
+      expect(text).toContain('call `request_file_upload`');
+      expect(text).toContain('then `apply_file_upload`');
+      expect(text).not.toContain('request_upload_token');
+      expect(text).toContain('`contentMode`');
+      expect(text).toContain('.docx/.pptx/.xlsx/.odt/.odp/.ods/.pdf');
+      expect(text).toContain('.eml/.msg');
+      expect(text).toContain('.doc/.ppt/.xls');
+    }
+  });
+
+  it('names the guide under the name this deployment gave it, in both places and in the pointer', async () => {
+    const layout = { ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' };
+    const section = sharedFileRulesSection(layout);
+    // Ours first, then the organisation's own AGENTS.md, then the pre-rename name.
+    expect(section).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
+    expect(section).toContain('`CLAUDE.md` on a knowledge base seeded before it was renamed');
+    // The platform files a move refuses list the guide under its own name too.
+    expect(section).toContain('`HEXIS.md`');
+    expect(composeAgentInstructions(null, layout).instructions).toContain(section);
+    expect(renderTemplateText(await guideTemplate(), layout)).toContain(section);
+    expect(sharedRulesPointer(layout)).toBe(` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in HEXIS.md.`);
+  });
+
+  it('keeps the pointer bounded whatever the guide is called', () => {
+    // The pointer rides on every file tool, so its length is not the guide's
+    // business: `validateFilename` allows a 255-byte name, and an unbounded
+    // pointer would reach 318 characters and push `file_stat` past the
+    // description cap — on a renamed deployment only, which no measurement
+    // taken under the default layout would ever show.
+    const nameOfLength = (n: number): string => `${'x'.repeat(n - 3)}.md`;
+    for (const length of [9, POINTER_GUIDE_NAME_BUDGET, POINTER_GUIDE_NAME_BUDGET + 1, 120, 255]) {
+      const pointer = sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: nameOfLength(length) });
+      expect(pointer.length, `a ${length}-character name`).toBeLessThanOrEqual(SHARED_RULES_POINTER_MAX);
+    }
+    // Up to the budget the file is NAMED, which is the better sentence.
+    const named = nameOfLength(POINTER_GUIDE_NAME_BUDGET);
+    expect(sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: named })).toContain(named);
+    // Past it the guide is named by its role instead — a sentence that still
+    // says where to look, rather than a catalog entry the client cuts.
+    const tooLong = nameOfLength(POINTER_GUIDE_NAME_BUDGET + 1);
+    const fallback = sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: tooLong });
+    expect(fallback).not.toContain(tooLong);
+    expect(fallback).toBe(` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in the agent guide at the KB root.`);
+    // Either way the section's first rule still names the file, so the name is
+    // never actually lost.
+    expect(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, agentsFile: tooLong })).toContain(tooLong);
+  });
+
+  it('points at the section with one short sentence under the default name', () => {
+    expect(sharedRulesPointer(DEFAULT_KB_LAYOUT)).toBe(
+      ' Shared rules for all file tools: see "Working with files" in AGENTS.md.',
+    );
+    // An unset guide name means the default, as it does everywhere else.
+    expect(sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: undefined })).toBe(
+      sharedRulesPointer(DEFAULT_KB_LAYOUT),
+    );
+  });
+});
+
+describe('the guide template asks for the rules rather than repeating them', () => {
+  it('carries the placeholder once, and no rule text of its own', async () => {
+    const template = await guideTemplate();
+    expect(template.split(SHARED_FILE_RULES_PLACEHOLDER)).toHaveLength(2);
+    // The rules are not ALSO written into the template — that is the copy that
+    // would drift. Checked on a fragment of each rule rather than on the whole.
+    for (const rule of sharedFileRules(DEFAULT_KB_LAYOUT)) {
+      expect(template, rule.id).not.toContain(rule.body.slice(0, 60));
+    }
+  });
+
+  it('renders the placeholder nowhere else, so other managed files are untouched', async () => {
+    const access = await readFile(path.join(defaultKbTemplateDir(), 'access.md'), 'utf8');
+    expect(access).not.toContain(SHARED_FILE_RULES_PLACEHOLDER);
+    // So rendering it gains no rule text: whatever the layout renderer does to
+    // its own tokens, the section is nowhere in the result.
+    const rendered = renderTemplateText(access, DEFAULT_KB_LAYOUT);
+    expect(rendered).not.toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    expect(rendered).not.toContain(`## ${SHARED_RULES_SECTION}`);
+  });
+
+  it('leaves no placeholder behind once rendered', async () => {
+    const guide = renderTemplateText(await guideTemplate(), DEFAULT_KB_LAYOUT);
+    expect(guide).not.toContain('{{');
+  });
+
+  it('renders the layout tokens first, then injects the rules — so the rules are never re-rendered', async () => {
+    // A layout the two orders DISAGREE on, which an ordinary one does not: the
+    // section states the knowledge-base folder's name, so a deployment whose
+    // folder is literally called `{{skillsDir}}` puts a layout token inside the
+    // rendered section. Injecting first would then rewrite it on the second
+    // pass and the guide would name the skills folder where the rule means the
+    // knowledge-base one. Pathological on purpose: it is the only kind of input
+    // on which the order is observable at all, which is why a test that pins
+    // the order has to use one.
+    const layout = { ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' };
+    const section = sharedFileRulesSection(layout);
+    expect(section).toContain('{{skillsDir}}/');
+
+    const template = `Skills live in {{skillsDir}}/.\n\n${SHARED_FILE_RULES_PLACEHOLDER}\n`;
+    const rendered = renderTemplateText(template, layout);
+    // The author's token is rendered, and the section survives byte for byte.
+    expect(rendered).toBe(`Skills live in Playbooks/.\n\n${section}\n`);
+
+    // And the other order really does differ on this input, so the assertion
+    // above is load-bearing rather than true of both.
+    const injectedFirst = renderKbLayoutPlaceholders(
+      template.replaceAll(SHARED_FILE_RULES_PLACEHOLDER, () => section),
+      layout,
+    );
+    expect(injectedFirst).not.toBe(rendered);
+    expect(injectedFirst).not.toContain(section);
+    expect(injectedFirst).toContain('`Playbooks/`) and git metadata are refused');
+  });
+});
+
+describe('the handshake text stays inside the length it pins', () => {
+  it('holds the shared section under its own cap', () => {
+    const section = sharedFileRulesSection(DEFAULT_KB_LAYOUT);
+    expect(
+      section.length,
+      `the shared rules are ${section.length} characters (cap ${SHARED_FILE_RULES_CAP})`,
+    ).toBeLessThanOrEqual(SHARED_FILE_RULES_CAP);
+  });
+
+  it('holds the worst-case instructions under the cap the caps add up to', () => {
+    // Header + the shared rules at their cap + a preamble at ITS cap + the
+    // marker a cut appends + the two blank lines between the three parts.
+    const worstCase = PLATFORM_HEADER.length + 2 + SHARED_FILE_RULES_CAP + 2 + PREAMBLE_CAP + 1 + PREAMBLE_TRUNCATION_MARKER.length;
+    expect(worstCase).toBeLessThanOrEqual(INSTRUCTIONS_CAP);
+    // And what an actual over-long preamble produces is under it too.
+    const composed = composeAgentInstructions('x'.repeat(PREAMBLE_CAP * 2));
+    expect(composed.truncated).toBe(true);
+    expect(composed.instructions.length).toBeLessThanOrEqual(INSTRUCTIONS_CAP);
+  });
+
+  it('hands the platform-owned text back as `header`, apart from the admin preamble', () => {
+    const out = composeAgentInstructions('We sell permits.');
+    expect(out.header).toBe(platformInstructions(DEFAULT_KB_LAYOUT));
+    expect(out.header).toContain(PLATFORM_HEADER);
+    expect(out.header).toContain(`## ${SHARED_RULES_SECTION}`);
+    expect(out.preamble).toBe('We sell permits.');
+    expect(out.instructions).toBe(`${out.header}\n\nWe sell permits.`);
+  });
+});

package/src/modules/agent-instructions/agent-instructions.routes.ts

@@ -1,4 +1,5 @@
 import express, { type RequestHandler } from 'express';
+import type { KbLayout } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('agent-instructions');
@@ -22,7 +23,16 @@ import type { AgentPreambleReader } from './read-preamble.js';
  * name folders the caller cannot open. A reader throw is a 500, never an
  * empty preamble, so the caller's own fallback decides what to send.
  */
-export function createAgentInstructionsRoutes(manualAuth: RequestHandler, readPreamble: AgentPreambleReader): express.Router {
+export function createAgentInstructionsRoutes(
+  manualAuth: RequestHandler,
+  readPreamble: AgentPreambleReader,
+  /**
+   * The layout in effect, read per request — the shared file rules name the
+   * managed guide, whose name the setup save may change without a restart.
+   * Optional so a construction with no layout in hand gets `AGENTS.md`.
+   */
+  kbLayout?: () => KbLayout,
+): express.Router {
   const router = express.Router();
 
   router.get('/agent/instructions', manualAuth, async (_req, res) => {
@@ -30,7 +40,7 @@ export function createAgentInstructionsRoutes(manualAuth: RequestHandler, readPr
     // successful one: the contract is on the route, not on the happy path.
     res.setHeader('Cache-Control', 'no-store');
     try {
-      res.json(composeAgentInstructions(await readPreamble()));
+      res.json(composeAgentInstructions(await readPreamble(), kbLayout?.()));
     } catch (err) {
       log.error('reading mcp-description.md failed:', { err });
       res.status(500).json({ error: 'Failed to read the agent instructions' });

package/src/modules/agent-instructions/compose.ts

@@ -1,7 +1,9 @@
 /**
  * What a connected agent is told at the start of an MCP session, composed
- * from two layers: a platform header the code owns, and the deployment
- * preamble an admin writes in `mcp-description.md` at the repository root.
+ * from three layers: a platform header the code owns, the rules every file tool
+ * shares (`shared-file-rules.ts`, the same text the managed guide carries), and
+ * the deployment preamble an admin writes in `mcp-description.md` at the
+ * repository root.
  *
  * Two channels carry the result. The full text goes out as `instructions` on
  * the initialize handshake, which Claude Code, Claude Desktop and Cursor place
@@ -21,11 +23,14 @@
 // apart. Re-exported here because this module is where the backend reads them
 // from.
 import {
+  DEFAULT_KB_LAYOUT,
   PREAMBLE_CAP,
   PREAMBLE_FILE,
   TOOL_PREFIX_CAP,
   stripHtmlComments,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
+import { sharedFileRulesSection } from './shared-file-rules.js';
 
 export { PREAMBLE_CAP, PREAMBLE_FILE, TOOL_PREFIX_CAP };
 
@@ -53,13 +58,42 @@ export const PLATFORM_HEADER =
  */
 export const TOOL_PREFIX_LINE = "This organisation's knowledge base. Search it before answering from memory.";
 
+/**
+ * The whole platform-owned part of the handshake text: what Hexis is, then the
+ * rules every file tool shares (see `shared-file-rules.ts`). This is what the
+ * `header` field carries and what the card shows as fixed and not editable;
+ * the admin's preamble follows it.
+ *
+ * A FUNCTION of the layout, because the shared rules name the managed guide
+ * and its file name is a deployment setting.
+ */
+export function platformInstructions(layout: KbLayout): string {
+  return `${PLATFORM_HEADER}\n\n${sharedFileRulesSection(layout)}`;
+}
+
+/**
+ * The ceiling on the WHOLE handshake text, pinned by a test.
+ *
+ * No client publishes a limit for `instructions` — what was observed being cut
+ * was tool descriptions — so this is not a measured client limit but the
+ * arithmetic ceiling of the parts, held low enough that it stays a plausible
+ * system-prompt insert (~3,500 tokens): the header, the shared rules under their
+ * own cap, and the preamble under its cap plus the marker a cut appends. The
+ * test is what makes it a ceiling rather than a hope: a shared rule that grew
+ * past it fails before it reaches an agent.
+ */
+export const INSTRUCTIONS_CAP = 14_000;
+
 /** The one-line marker that replaces everything past the preamble cap. */
 export const PREAMBLE_TRUNCATION_MARKER = `[preamble truncated at ${PREAMBLE_CAP.toLocaleString('en-US')} characters; shorten ${PREAMBLE_FILE}]`;
 
 export interface ComposedAgentInstructions {
-  /** The header, then the preamble body when there is one. Sent on the initialize handshake. */
+  /** The platform text, then the preamble body when there is one. Sent on the initialize handshake. */
   instructions: string;
-  /** The platform header alone, so a card can show the fixed part apart from the admin's. */
+  /**
+   * The platform-owned text alone — the header and the shared file rules — so a
+   * card can show the fixed part apart from the admin's.
+   */
   header: string;
   /** The preamble body as sent (cut and marked when over the cap); empty when there is none. */
   preamble: string;
@@ -84,15 +118,24 @@ export interface ComposedAgentInstructions {
  * absent). HTML comments are private notes and never leave the file; an
  * unterminated `<!--` strips everything after it, so the most likely editing
  * slip withholds text rather than leaking it.
+ *
+ * `layout` decides only the guide's name inside the shared rules, and defaults
+ * to the standard one — a caller with no layout in hand (a test, a surface that
+ * predates the setting) gets `AGENTS.md`, which is what an unset name means
+ * everywhere else.
  */
-export function composeAgentInstructions(preamble: string | null): ComposedAgentInstructions {
+export function composeAgentInstructions(
+  preamble: string | null,
+  layout: KbLayout = DEFAULT_KB_LAYOUT,
+): ComposedAgentInstructions {
+  const platform = platformInstructions(layout);
   const { text, unterminated } = stripHtmlComments(preamble ?? '');
   const normalized = text.replace(/\r\n?/g, '\n');
   const stripped = normalized.trim();
   const preambleChars = stripped.length;
   const truncated = preambleChars > PREAMBLE_CAP;
   const body = truncated ? `${cutAtCodePoint(stripped, PREAMBLE_CAP)}\n${PREAMBLE_TRUNCATION_MARKER}` : stripped;
-  const instructions = body ? `${PLATFORM_HEADER}\n\n${body}` : PLATFORM_HEADER;
+  const instructions = body ? `${platform}\n\n${body}` : platform;
 
   // Classified UNTRIMMED: the leading indentation of a first line is what
   // makes it an indented code block, and the trim above would turn that
@@ -105,7 +148,7 @@ export function composeAgentInstructions(preamble: string | null): ComposedAgent
 
   return {
     instructions,
-    header: PLATFORM_HEADER,
+    header: platform,
     preamble: body,
     toolPrefix,
     toolPrefixLine: TOOL_PREFIX_LINE,

package/src/modules/agent-instructions/index.ts

@@ -1,6 +1,8 @@
 export {
   composeAgentInstructions,
   prefixToolDescription,
+  platformInstructions,
+  INSTRUCTIONS_CAP,
   PLATFORM_HEADER,
   TOOL_PREFIX_LINE,
   PREAMBLE_CAP,
@@ -10,5 +12,15 @@ export {
   PREAMBLE_TRUNCATION_MARKER,
   type ComposedAgentInstructions,
 } from './compose.js';
+export {
+  POINTER_GUIDE_NAME_BUDGET,
+  SHARED_FILE_RULES_CAP,
+  SHARED_RULES_POINTER_MAX,
+  SHARED_RULES_SECTION,
+  sharedFileRules,
+  sharedFileRulesSection,
+  sharedRulesPointer,
+  type SharedFileRule,
+} from './shared-file-rules.js';
 export { readAgentPreamble, type AgentPreambleReader, type PreambleWorkspace } from './read-preamble.js';
 export { createAgentInstructionsRoutes } from './agent-instructions.routes.js';