@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/agent-instructions/__tests__/agent-instructions.route.test.ts

@@ -0,0 +1,100 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createManualAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+import type { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import { createAgentInstructionsRoutes } from '../agent-instructions.routes.js';
+import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../compose.js';
+
+/**
+ * `GET /agent/instructions` behind the REAL manual-auth gate, with the three
+ * credential stores faked at their seams: a connection key, an internal token
+ * and a browser JWT all get in, nothing else does, and the response is the
+ * composer's result with the no-store header. Absence and failure of the file
+ * stay distinguishable: ENOENT is the header alone, anything else is a 500.
+ */
+
+let httpServer: HttpServer | undefined;
+
+const CONNECTION_KEY = 'bevel_abc';
+const INTERNAL_TOKEN = 'bit_xyz';
+const BROWSER_JWT = 'jwt.session.token';
+
+async function serve(readPreamble: () => Promise<string | null>): Promise<string> {
+  const externalKeys = {
+    looksLikeExternalApiKey: (t: string) => t.startsWith('bevel_'),
+    verifyAndLoadToken: async (t: string) => (t === CONNECTION_KEY ? { user: { id: 'u-key' }, tokenId: 'tok-1' } : null),
+  } as unknown as IExternalApiKeyService;
+  const internalTokens = {
+    looksLikeInternalToken: (t: string) => t.startsWith('bit_'),
+    verify: (t: string) => (t === INTERNAL_TOKEN ? { userId: 'u-internal' } : null),
+  } as unknown as InternalTokenService;
+  const authService = {
+    verifyToken: (t: string) => {
+      if (t !== BROWSER_JWT) throw new Error('bad jwt');
+      return { userId: 'u-browser' };
+    },
+  } as unknown as AuthService;
+  const app = express();
+  app.use('/api', createAgentInstructionsRoutes(createManualAuthMiddleware(externalKeys, internalTokens, authService), readPreamble));
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}/api/agent/instructions`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.restoreAllMocks();
+});
+
+describe('GET /agent/instructions', () => {
+  it('answers 200 for a connection key, an internal token and a browser JWT alike', async () => {
+    const url = await serve(async () => 'Acme builds solar farms.\n');
+    for (const bearer of [CONNECTION_KEY, INTERNAL_TOKEN, BROWSER_JWT]) {
+      const res = await fetch(url, { headers: { Authorization: `Bearer ${bearer}` } });
+      expect(res.status, bearer).toBe(200);
+      expect(res.headers.get('cache-control')).toBe('no-store');
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.instructions).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.`);
+      expect(body.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Acme builds solar farms.`);
+      expect(body).toMatchObject({
+        truncated: false,
+        preambleChars: 'Acme builds solar farms.'.length,
+        toolPrefixTruncated: false,
+        unterminatedComment: false,
+      });
+    }
+  });
+
+  it('answers 401 without a credential, and for an invalid one', async () => {
+    const url = await serve(async () => 'x');
+    expect((await fetch(url)).status).toBe(401);
+    expect((await fetch(url, { headers: { Authorization: 'Bearer bevel_wrong' } })).status).toBe(401);
+    expect((await fetch(url, { headers: { Authorization: 'Bearer not-a-session' } })).status).toBe(401);
+  });
+
+  it('a missing file yields the header alone', async () => {
+    const url = await serve(async () => null);
+    const res = await fetch(url, { headers: { Authorization: `Bearer ${CONNECTION_KEY}` } });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { instructions: string; toolPrefix: string; preambleChars: number };
+    expect(body.instructions).toBe(PLATFORM_HEADER);
+    expect(body.toolPrefix).toBe(TOOL_PREFIX_LINE);
+    expect(body.preambleChars).toBe(0);
+  });
+
+  it('a read error other than ENOENT is a 500, never an empty preamble', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const url = await serve(async () => {
+      throw Object.assign(new Error('disk'), { code: 'EIO' });
+    });
+    const res = await fetch(url, { headers: { Authorization: `Bearer ${CONNECTION_KEY}` } });
+    expect(res.status).toBe(500);
+    // The failure is no more cacheable than a success.
+    expect(res.headers.get('cache-control')).toBe('no-store');
+  });
+});

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

@@ -0,0 +1,256 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PLATFORM_HEADER,
+  PREAMBLE_CAP,
+  PREAMBLE_TRUNCATION_MARKER,
+  TOOL_PREFIX_CAP,
+  TOOL_PREFIX_LINE,
+  composeAgentInstructions,
+  prefixToolDescription,
+} from '../compose.js';
+
+/**
+ * The composer is pure, so every rule of the two texts is pinned here: what
+ * an absent or empty preamble yields, how comments are withheld, where both
+ * caps cut, and that a cut never splits a character.
+ */
+
+describe('composeAgentInstructions: the handshake text', () => {
+  it('sends the header alone for an absent, empty, whitespace or comment-only preamble', () => {
+    for (const raw of [null, '', '   \n\n', '<!-- notes to myself -->', '<!--\nline one\nline two\n-->\n']) {
+      const out = composeAgentInstructions(raw);
+      expect(out.instructions, JSON.stringify(raw)).toBe(PLATFORM_HEADER);
+      expect(out.toolPrefix).toBe(TOOL_PREFIX_LINE);
+      expect(out.truncated).toBe(false);
+      expect(out.toolPrefixTruncated).toBe(false);
+      expect(out.preambleChars).toBe(0);
+      expect(out.unterminatedComment).toBe(false);
+    }
+  });
+
+  it('is the header, a blank line, then the preamble body', () => {
+    const out = composeAgentInstructions('We sell permits.\n\nLook in Permitting/ first.\n');
+    expect(out.instructions).toBe(`${PLATFORM_HEADER}\n\nWe sell permits.\n\nLook in Permitting/ first.`);
+    expect(out.preambleChars).toBe('We sell permits.\n\nLook in Permitting/ first.'.length);
+  });
+
+  it('hands the two parts and the fixed prefix line back separately, for the card', () => {
+    const out = composeAgentInstructions('We sell permits.');
+    expect(out.header).toBe(PLATFORM_HEADER);
+    expect(out.preamble).toBe('We sell permits.');
+    expect(out.toolPrefixLine).toBe(TOOL_PREFIX_LINE);
+    expect(out.toolPrefix.startsWith(out.toolPrefixLine)).toBe(true);
+    expect(composeAgentInstructions(null).preamble).toBe('');
+    // The preamble part carries the marker when cut, exactly as sent.
+    expect(composeAgentInstructions('x'.repeat(PREAMBLE_CAP + 1)).preamble.endsWith(PREAMBLE_TRUNCATION_MARKER)).toBe(true);
+  });
+
+  it('withholds every HTML comment from both outputs', () => {
+    const out = composeAgentInstructions('<!-- private: do not send -->Public line.<!-- more notes -->\n\nSecond paragraph.');
+    expect(out.instructions).not.toContain('private');
+    expect(out.instructions).not.toContain('more notes');
+    expect(out.instructions).toContain('Public line.');
+    expect(out.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Public line.`);
+    expect(out.unterminatedComment).toBe(false);
+  });
+
+  it('an unterminated comment withholds everything after it and is reported', () => {
+    const out = composeAgentInstructions('Visible.\n\n<!-- forgot to close\nSecret folder names\n');
+    expect(out.instructions).toBe(`${PLATFORM_HEADER}\n\nVisible.`);
+    expect(out.instructions).not.toContain('Secret');
+    expect(out.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Visible.`);
+    expect(out.unterminatedComment).toBe(true);
+  });
+
+  it('sends exactly the cap whole, and cuts one past it with the marker', () => {
+    const exact = 'a'.repeat(PREAMBLE_CAP);
+    const atCap = composeAgentInstructions(exact);
+    expect(atCap.truncated).toBe(false);
+    expect(atCap.instructions).toBe(`${PLATFORM_HEADER}\n\n${exact}`);
+    expect(atCap.instructions).not.toContain('truncated');
+
+    const over = composeAgentInstructions(`${exact}b`);
+    expect(over.truncated).toBe(true);
+    expect(over.instructions).toBe(`${PLATFORM_HEADER}\n\n${exact}\n${PREAMBLE_TRUNCATION_MARKER}`);
+    expect(PREAMBLE_TRUNCATION_MARKER).toContain('6,000');
+    expect(PREAMBLE_TRUNCATION_MARKER).toContain('mcp-description.md');
+  });
+
+  it('reports the count before truncation', () => {
+    const out = composeAgentInstructions('x'.repeat(PREAMBLE_CAP + 1234));
+    expect(out.preambleChars).toBe(PREAMBLE_CAP + 1234);
+    expect(out.truncated).toBe(true);
+  });
+
+  it('counts after comment stripping, not the raw file', () => {
+    const out = composeAgentInstructions('<!-- a very long private note -->Short.');
+    expect(out.preambleChars).toBe('Short.'.length);
+  });
+
+  it('a cut that would split a surrogate pair moves before it', () => {
+    // 5,999 ASCII units, then an astral character (two UTF-16 units): unit
+    // 6,000 is its high surrogate, so the cut must land before it.
+    const raw = `${'a'.repeat(PREAMBLE_CAP - 1)}😀tail`;
+    const out = composeAgentInstructions(raw);
+    expect(out.truncated).toBe(true);
+    const body = out.instructions.slice(PLATFORM_HEADER.length + 2);
+    const sent = body.slice(0, body.indexOf('\n'));
+    expect(sent).toBe('a'.repeat(PREAMBLE_CAP - 1));
+    expect(sent.length).toBe(PREAMBLE_CAP - 1);
+    // Nothing in what was sent is a lone surrogate.
+    expect(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(out.instructions)).toBe(false);
+  });
+});
+
+describe('composeAgentInstructions: the tool prefix', () => {
+  it('starts with the fixed line, then the first paragraph, collapsed to one line', () => {
+    const out = composeAgentInstructions('Acme builds solar\nfarms in Spain.\n\nSecond paragraph.');
+    expect(out.toolPrefix).toBe(`${TOOL_PREFIX_LINE} Acme builds solar farms in Spain.`);
+    expect(out.toolPrefixChars).toBe(out.toolPrefix.length);
+    expect(out.toolPrefixTruncated).toBe(false);
+  });
+
+  it('skips headings: a heading-led file still yields the first real paragraph', () => {
+    const out = composeAgentInstructions('# Acme knowledge base\n\n## Scope\n\nWhat we know about permits.\n');
+    expect(out.toolPrefix).toBe(`${TOOL_PREFIX_LINE} What we know about permits.`);
+    // A heading directly above text in the same block is dropped, not merged.
+    const tight = composeAgentInstructions('## Scope\nWhat we know about permits.');
+    expect(tight.toolPrefix).toBe(`${TOOL_PREFIX_LINE} What we know about permits.`);
+  });
+
+  it('falls back to the fixed line alone for an empty or heading-only preamble', () => {
+    for (const raw of [null, '', '# Only a title\n\n## And a subtitle', 'Setext title\n===\n\nAnother\n---', '---\n\n***']) {
+      expect(composeAgentInstructions(raw).toolPrefix, JSON.stringify(raw)).toBe(TOOL_PREFIX_LINE);
+    }
+  });
+
+  it('skips setext headings and thematic breaks the same way it skips ATX headings', () => {
+    expect(composeAgentInstructions('Acme knowledge base\n===\n\nWhat we know about permits.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} What we know about permits.`,
+    );
+    // The underline directly above text in the same block heads only what is above it.
+    expect(composeAgentInstructions('Scope\n---\nWhat we know about permits.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} What we know about permits.`,
+    );
+    expect(composeAgentInstructions('---\n\nAfter the rule.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} After the rule.`);
+    // A lone dash line is a rule, not an underline: it never swallows text above it.
+    expect(composeAgentInstructions('- - -\n\nList-looking rule first.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} List-looking rule first.`,
+    );
+  });
+
+  it('a rule after a list item is a thematic break, not the underline of a setext heading', () => {
+    // CommonMark: the underline cannot be a lazy continuation of a list item or a
+    // blockquote, so the item survives and the rule is dropped like any other.
+    expect(composeAgentInstructions('- Permits\n---\n\nWhat we know about permits.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} - Permits`,
+    );
+    expect(composeAgentInstructions('> Permits\n---\n\nWhat we know about permits.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} > Permits`,
+    );
+    // The lines that continue an item or a quote belong to it, so a rule beneath them is a break too.
+    expect(composeAgentInstructions('- Item one\n  continuation\n---\n\nWhat we know.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} - Item one continuation`,
+    );
+    expect(composeAgentInstructions('> quote\ncontinued\n---\n\nWhat we know.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} > quote continued`,
+    );
+    // A bare `===` beneath a container is literal text to CommonMark, but a line of rule characters is never content worth sending.
+    expect(composeAgentInstructions('- Item\nPara\n===\n\nWhat we know.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} - Item Para`);
+  });
+
+  it('a spaced thematic break is a break, not a list item, so the setext heading beneath it is still dropped', () => {
+    expect(composeAgentInstructions('* * *\nTitle\n===\n\nWhat we know.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} What we know.`);
+    expect(composeAgentInstructions('- - -\nTitle\n---\n\nWhat we know.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} What we know.`);
+  });
+
+  it('a fenced code block is not a paragraph: a rule inside it is code, and the prose after it is the prefix', () => {
+    expect(
+      composeAgentInstructions('```yaml\nkey: value\n---\nother: value\n```\n\nWhat we know about permits.').toolPrefix,
+    ).toBe(`${TOOL_PREFIX_LINE} What we know about permits.`);
+    // Blank lines inside the fence do not end it; only a closing fence does.
+    expect(composeAgentInstructions('~~~\nfoo\n\n---\n~~~\nAfter the block.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} After the block.`,
+    );
+    // A fence that never closes runs to the end of the file, as in CommonMark.
+    expect(composeAgentInstructions('```\nnever closed\n\nstill code').toolPrefix).toBe(TOOL_PREFIX_LINE);
+  });
+
+  it('indentation decides what is a fence: three columns still open one, four make it indented code', () => {
+    // A ``` indented four columns is the content of an indented code block,
+    // not a fence — so it cannot swallow the prose after it as an unclosed
+    // one. At the very start of the file too: the text is classified before
+    // it is trimmed, so the first line keeps the indentation that makes it code.
+    expect(composeAgentInstructions('    ```\n    looks like a fence\n\nProse after the code.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} Prose after the code.`,
+    );
+    // An indented code block is not a paragraph, whatever it says — at the
+    // start, after a heading, after a setext heading and after a rule, with
+    // or without a blank line between: each of those ends what came before.
+    expect(composeAgentInstructions('    code line\n\tanother\n\nProse.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} Prose.`);
+    expect(composeAgentInstructions('# Title\n    code\n\nProse.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} Prose.`);
+    expect(composeAgentInstructions('Title\n===\n    code\nProse.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} Prose.`);
+    expect(composeAgentInstructions('---\n    code\n\nProse.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} Prose.`);
+    // Up to three columns the fence is a fence, and so is its closer.
+    expect(composeAgentInstructions('   ```\n---\n   ```\nProse.').toolPrefix).toBe(`${TOOL_PREFIX_LINE} Prose.`);
+    // Inside a paragraph, indentation is a continuation, not code — and a
+    // continuation is text whatever it looks like once trimmed: `    # x`
+    // is not a heading and `    ---` is not a rule, so neither ends the
+    // paragraph nor drops the lines after it.
+    expect(composeAgentInstructions('First line\n    continued.\n\nNext.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} First line continued.`,
+    );
+    expect(composeAgentInstructions('First line\n    # not a heading\n    still here.\n\nNext.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} First line # not a heading still here.`,
+    );
+    expect(composeAgentInstructions('First line\n    ---\n    still here.\n\nNext.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} First line --- still here.`,
+    );
+  });
+
+  it("a fence closes only on a line of the opener's character, at least as long", () => {
+    // Mixed characters do not close it, so what follows stays code.
+    expect(composeAgentInstructions('```\ncode\n```~\nmore code\n```\n\nProse.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} Prose.`,
+    );
+    // A shorter run does not close it; a longer one does.
+    expect(composeAgentInstructions('````\ncode\n```\nstill code\n`````\n\nProse.').toolPrefix).toBe(
+      `${TOOL_PREFIX_LINE} Prose.`,
+    );
+  });
+
+  it('CRLF input still yields the first paragraph', () => {
+    const out = composeAgentInstructions('# Title\r\n\r\nFirst paragraph.\r\n\r\nSecond.\r\n');
+    expect(out.toolPrefix).toBe(`${TOOL_PREFIX_LINE} First paragraph.`);
+    expect(out.instructions).toBe(`${PLATFORM_HEADER}\n\n# Title\n\nFirst paragraph.\n\nSecond.`);
+  });
+
+  it('is at most the cap, still starting with the fixed line, and reports the count before the cut', () => {
+    const long = 'w'.repeat(TOOL_PREFIX_CAP * 2);
+    const out = composeAgentInstructions(long);
+    expect(out.toolPrefix.length).toBe(TOOL_PREFIX_CAP);
+    expect(out.toolPrefix.startsWith(TOOL_PREFIX_LINE)).toBe(true);
+    expect(out.toolPrefixTruncated).toBe(true);
+    expect(out.toolPrefixChars).toBe(TOOL_PREFIX_LINE.length + 1 + long.length);
+  });
+
+  it('never splits a surrogate pair at the prefix cap', () => {
+    // Pad so that unit 300 of the prefix is the high surrogate of an astral character.
+    const padding = 'p'.repeat(TOOL_PREFIX_CAP - TOOL_PREFIX_LINE.length - 2);
+    const out = composeAgentInstructions(`${padding}😀zz`);
+    expect(out.toolPrefixTruncated).toBe(true);
+    expect(out.toolPrefix.length).toBe(TOOL_PREFIX_CAP - 1);
+    expect(out.toolPrefix.endsWith(padding)).toBe(true);
+  });
+});
+
+describe('prefixToolDescription', () => {
+  it('is the prefix, a blank line, then the original description', () => {
+    expect(prefixToolDescription('P', 'Read a file.')).toBe('P\n\nRead a file.');
+  });
+
+  it('is the prefix alone for a tool with no description', () => {
+    expect(prefixToolDescription('P', undefined)).toBe('P');
+    expect(prefixToolDescription('P', '')).toBe('P');
+  });
+});

package/src/modules/agent-instructions/__tests__/read-preamble.test.ts

@@ -0,0 +1,135 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { readAgentPreamble, type PreambleWorkspace } from '../read-preamble.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+
+/** The one disk, as production wires it. */
+const disk = new NodeFs();
+
+/**
+ * The reader against a real directory: a regular file is read, an absent one
+ * is `null`, and anything that is not a regular file (a symlink above all,
+ * since this file is read as the platform and broadcast to every agent) is
+ * refused with an error rather than followed or reported as absent.
+ */
+
+const KB = 'knowledge-base';
+let root: string;
+let wsDir: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-preamble-'));
+  wsDir = path.join(root, workspaceIdForBranch(DEFAULT_BRANCH));
+  await fs.mkdir(path.join(wsDir, KB), { recursive: true });
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+function workspace(): PreambleWorkspace & { getOrCreateForBranch: ReturnType<typeof vi.fn>; getWorkspacePath: ReturnType<typeof vi.fn> } {
+  return {
+    getOrCreateForBranch: vi.fn(async () => ({ id: workspaceIdForBranch(DEFAULT_BRANCH) })) as never,
+    getWorkspacePath: vi.fn(async () => wsDir) as never,
+  };
+}
+
+describe('readAgentPreamble', () => {
+  it('reads the default branch copy at <kbDirName>/mcp-description.md, creating the workspace first', async () => {
+    await fs.writeFile(path.join(wsDir, KB, 'mcp-description.md'), 'Acme.\n', 'utf8');
+    const ws = workspace();
+    expect(await readAgentPreamble(ws, KB, disk)).toBe('Acme.\n');
+    expect(ws.getOrCreateForBranch).toHaveBeenCalledWith(DEFAULT_BRANCH);
+    expect(ws.getWorkspacePath).toHaveBeenCalledWith(workspaceIdForBranch(DEFAULT_BRANCH));
+  });
+
+  it("spells the path with the deployment's own KB dir name", async () => {
+    await fs.mkdir(path.join(wsDir, 'kb'), { recursive: true });
+    await fs.writeFile(path.join(wsDir, 'kb', 'mcp-description.md'), 'Renamed root.', 'utf8');
+    expect(await readAgentPreamble(workspace(), 'kb', disk)).toBe('Renamed root.');
+    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull(); // the default-named root has none
+  });
+
+  it('a file that is not there is an absence, not a fault', async () => {
+    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull();
+  });
+
+  it('refuses a symlink: the secret it points at is never read, and it is not an absence either', async () => {
+    const secret = path.join(root, 'secret.txt');
+    await fs.writeFile(secret, 'DATABASE_URL=postgres://…', 'utf8');
+    await fs.symlink(secret, path.join(wsDir, KB, 'mcp-description.md'));
+    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/symlink, not a regular file/);
+  });
+
+  it('refuses a repository folder reached through a link — the whole path must be its own, not only the file', async () => {
+    // The file is a regular file; the folder above it is a link elsewhere.
+    const elsewhere = path.join(root, 'elsewhere');
+    await fs.mkdir(elsewhere, { recursive: true });
+    await fs.writeFile(path.join(elsewhere, 'mcp-description.md'), 'Not the repository.', 'utf8');
+    await fs.rm(path.join(wsDir, KB), { recursive: true });
+    await fs.symlink(elsewhere, path.join(wsDir, KB), process.platform === 'win32' ? 'junction' : 'dir');
+    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/through a symlink/);
+  });
+
+  it('reads through a link ABOVE the workspace — a mounted volume is the operator\'s, not the repository\'s', async () => {
+    await fs.writeFile(path.join(wsDir, KB, 'mcp-description.md'), 'Acme.\n', 'utf8');
+    const mount = path.join(root, 'mount');
+    await fs.symlink(wsDir, mount, process.platform === 'win32' ? 'junction' : 'dir');
+    const ws = workspace();
+    ws.getWorkspacePath.mockImplementation(async () => mount);
+    expect(await readAgentPreamble(ws, KB, disk)).toBe('Acme.\n');
+  });
+
+  it('refuses a directory squatting the name', async () => {
+    await fs.mkdir(path.join(wsDir, KB, 'mcp-description.md'));
+    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/directory, not a regular file/);
+  });
+
+  it('a KB directory that is a regular file is an ABSENT preamble, the shared rule for "nothing can be there"', async () => {
+    // The lstat below it fails with ENOTDIR. Nothing can live under a regular
+    // file, so this is absence — the same answer every other reader in the
+    // platform gives it (see `isAbsence`), not a fault to broadcast. A root
+    // squatted this way is the startup phase's to refuse, loudly, once.
+    await fs.rm(path.join(wsDir, KB), { recursive: true });
+    await fs.writeFile(path.join(wsDir, KB), 'not a directory', 'utf8');
+    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull();
+  });
+
+  it('an lstat that fails for any reason but absence throws, never an empty preamble', async () => {
+    // A disk fault (EACCES here) must never masquerade as "no preamble": the
+    // admin wrote one, and answering null would silently drop it from every
+    // agent session. Spied rather than staged, so the property holds on
+    // every platform.
+    const real = fs.lstat;
+    const spy = vi.spyOn(fs, 'lstat').mockImplementation(((p: string) =>
+      String(p).endsWith('mcp-description.md')
+        ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
+        : (real as (p: string) => Promise<unknown>).call(fs, p)) as never);
+    try {
+      await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toMatchObject({ code: 'EACCES' });
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  // Root reads a mode-000 file, and Windows has no mode bits to deny with, so neither can make the open fail.
+  it.skipIf(process.platform === 'win32' || process.getuid?.() === 0)('an open that fails for any reason but absence throws too', async () => {
+    const file = path.join(wsDir, KB, 'mcp-description.md');
+    await fs.writeFile(file, 'Acme.', 'utf8');
+    await fs.chmod(file, 0o000); // the lstat still passes; the open is what fails
+    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toMatchObject({ code: 'EACCES' });
+  });
+
+  it('a workspace that cannot be located throws too', async () => {
+    const eio = Object.assign(new Error('disk'), { code: 'EIO' });
+    const ws = workspace();
+    ws.getWorkspacePath.mockImplementation(async () => {
+      throw eio;
+    });
+    await expect(readAgentPreamble(ws, KB, disk)).rejects.toBe(eio);
+  });
+});

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

@@ -0,0 +1,41 @@
+import express, { type RequestHandler } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('agent-instructions');
+import { composeAgentInstructions } from './compose.js';
+import type { AgentPreambleReader } from './read-preamble.js';
+
+/**
+ * The agent-facing instructions route, mounted on the tools router beside
+ * `GET /agent/all-tools` and behind the same `manualAuth` (a connection key,
+ * an internal token or a browser JWT):
+ *
+ *   GET /agent/instructions   the composed text both channels are built from,
+ *                             as the composer returns it. The local `hexis-mcp`
+ *                             bridge reads it at startup; the External agent
+ *                             access card reads it to show what agents get.
+ *
+ * The hosted proxy does NOT call this: it composes in-process while building
+ * each request's server (see `McpService.createRequestServer`).
+ * `Cache-Control: no-store`
+ * because the text is privileged: it is read with platform rights and may
+ * 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 {
+  const router = express.Router();
+
+  router.get('/agent/instructions', manualAuth, async (_req, res) => {
+    // Set before the read, so a failure answer is no more cacheable than a
+    // 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()));
+    } catch (err) {
+      log.error('reading mcp-description.md failed:', { err });
+      res.status(500).json({ error: 'Failed to read the agent instructions' });
+    }
+  });
+
+  return router;
+}