@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/agent-guide/__tests__/agent-guide.tools.test.ts

@@ -0,0 +1,207 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { TOOL_DESCRIPTION_CAP } from '../../tool-registry/description-length.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ToolContext } from '../../tool-helpers/tool.contract.js';
+import { toolDef } from '../../tool-helpers/tool-def.js';
+import { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from '../agent-guide.tools.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { agentGuideSections, joinGuideSections, type RenderedGuideSection } from '../agent-guide.js';
+
+let server: Server | null = null;
+
+afterEach(async () => {
+  if (server) await new Promise<void>((resolve) => server!.close(() => resolve()));
+  server = null;
+});
+
+const SECTIONS: RenderedGuideSection[] = [
+  { id: 'introduction', title: 'Knowledge base', body: '# Knowledge base\n\nRead me.' },
+  { id: 'access-control', title: 'Access control', body: '## Access control\n\nWho may do what.' },
+  { id: 'knowledge-graph', title: 'Knowledge graph', body: '## Knowledge graph\n\nA distribution added this one.' },
+];
+
+describe('get_agent_guide', () => {
+  async function serve() {
+    const registry = new ToolRegistry();
+    const router = express.Router();
+    // Stands in for the connection-key auth: the caller is a signed-in reader.
+    const auth = (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+      req.toolAuth = { source: 'internal', userId: 'u', scope: 'read' };
+      next();
+    };
+    const resolve = async (): Promise<ToolContext> =>
+      ({
+        user: { id: 'u', email: 'a@x.io', name: 'A' },
+        scope: 'read',
+        source: 'internal',
+        abortSignal: new AbortController().signal,
+        workspaceService: {} as never,
+        workflowService: {} as never,
+        events: {} as never,
+        getFilesystem: async () => {
+          throw new Error('the guide reads no file');
+        },
+      }) as unknown as ToolContext;
+    let reads = 0;
+    let current: RenderedGuideSection[] = SECTIONS;
+    registerAgentGuideTool(registry, router, auth, createToolHandlerFactory(resolve), async () => {
+      reads += 1;
+      return current;
+    });
+    const sectionsNow = (sections: RenderedGuideSection[]) => {
+      current = sections;
+    };
+    // Another tool beside it, to see what the catalog does to each.
+    registry.registerExternalTool(
+      toolDef({ name: 'read_file', description: 'Read a file.', path: '/api/agent/tools/read_file', inputs: { type: 'object', properties: {} }, tags: [] }),
+    );
+
+    const web = express();
+    web.use(express.json());
+    web.use('/api', router);
+    server = await new Promise<Server>((resolve) => {
+      const s = web.listen(0, '127.0.0.1', () => resolve(s));
+    });
+    const port = (server.address() as AddressInfo).port;
+    const call = async (body: Record<string, unknown> = {}) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/agent/tools/${GET_AGENT_GUIDE_TOOL}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: 'Bearer x' },
+        body: JSON.stringify(body),
+      });
+      return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+    };
+    return { registry, call, reads: () => reads, sectionsNow };
+  }
+
+  it('is on both surfaces, says to call it first, and lists the sections the guide has now', async () => {
+    const { registry } = await serve();
+    for (const list of [registry.listExternal(), registry.listInternal()]) {
+      const def = (await list).find((t) => t.name === GET_AGENT_GUIDE_TOOL);
+      expect(def).toBeDefined();
+      expect(def!.description).toContain('ALWAYS call this first and read the guide before you do anything else');
+      expect(def!.description).toContain("`read_file` on `AGENTS.md` at the KB root");
+      // The sections, a distribution's own included, by id and title.
+      expect(def!.description).toContain(
+        'Sections: `introduction` (Knowledge base), `access-control` (Access control), `knowledge-graph` (Knowledge graph).',
+      );
+      // The one tool that does not open with "call get_agent_guide first".
+      expect(def!.description.startsWith(GUIDE_FIRST_SENTENCE)).toBe(false);
+      // The def wraps a tool's inputs as its request `body`; this one takes `section` and nothing else.
+      const body = (def!.inputs as { properties: { body: { properties?: Record<string, unknown> } } }).properties.body;
+      expect(Object.keys(body.properties ?? {})).toEqual(['section']);
+    }
+  });
+
+  it('puts the guide-first sentence at the front of every other tool the catalog lists', async () => {
+    const { registry } = await serve();
+    const read = (await registry.listExternal()).find((t) => t.name === 'read_file')!;
+    expect(read.description).toBe(`${GUIDE_FIRST_SENTENCE} Read a file.`);
+  });
+
+  it('returns the whole guide, or one section by id, composed when asked', async () => {
+    const { call, reads, sectionsNow } = await serve();
+    expect(await call()).toEqual({
+      status: 200,
+      body: {
+        guide: '# Knowledge base\n\nRead me.\n\n## Access control\n\nWho may do what.\n\n## Knowledge graph\n\nA distribution added this one.\n',
+        // The complete list, whatever the description had room for.
+        sections: [
+          { id: 'introduction', title: 'Knowledge base' },
+          { id: 'access-control', title: 'Access control' },
+          { id: 'knowledge-graph', title: 'Knowledge graph' },
+        ],
+      },
+    });
+    expect(await call({ section: 'access-control' })).toEqual({
+      status: 200,
+      body: { guide: '## Access control\n\nWho may do what.', section: 'access-control', title: 'Access control' },
+    });
+    // A section the guide does not have is refused with the ones it has.
+    const unknown = await call({ section: 'nope' });
+    expect(unknown.status).toBe(400);
+    expect(String(unknown.body.error)).toContain('The guide has no section "nope". Sections: `introduction`, `access-control`, `knowledge-graph`.');
+    // Composed per call, never cached here: what the reader answers NOW is
+    // what the next call returns, so a layout applied later is seen.
+    expect(reads()).toBe(3);
+    sectionsNow([{ id: 'introduction', title: 'Renamed', body: '# Renamed\n\nThe layout changed.' }]);
+    expect(await call()).toEqual({
+      status: 200,
+      body: { guide: '# Renamed\n\nThe layout changed.\n', sections: [{ id: 'introduction', title: 'Renamed' }] },
+    });
+    expect(await call({ section: 'introduction' })).toMatchObject({ status: 200, body: { title: 'Renamed' } });
+    expect((await call({ section: 'access-control' })).status).toBe(400);
+    expect(reads()).toBe(6);
+  });
+
+  it('stays under the cap whatever a distribution adds: titles go first, then ids beyond what fits are counted', async () => {
+    // A client cuts a long description from the end, and an id cut off is a
+    // section an agent cannot ask for — so the description never carries a
+    // cut list. Three forms, by what fits: ids with titles; ids alone; as
+    // many ids as fit and the count of the rest, with the complete list on
+    // the whole-guide response's `sections`.
+    const { registry, call, sectionsNow } = await serve();
+    const describedAs = async () => (await registry.listExternal()).find((t) => t.name === GET_AGENT_GUIDE_TOOL)!.description!;
+
+    // Forty sections with long titles: the ids fit, the titles do not.
+    const many = Array.from({ length: 40 }, (_, i) => ({
+      id: `section-${i}`,
+      title: `A title long enough that forty of them do not fit, number ${i}`,
+      body: `## Title ${i}\n\nBody.`,
+    }));
+    sectionsNow([...SECTIONS, ...many]);
+    const idsOnly = await describedAs();
+    expect(idsOnly.length).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    for (const section of [...SECTIONS, ...many]) expect(idsOnly).toContain(`\`${section.id}\``);
+    expect(idsOnly).not.toContain('(Knowledge base)');
+    expect(idsOnly).not.toContain(' more');
+
+    // Two hundred sections with long ids: not even the ids fit. The ones
+    // that do are listed whole, the rest are counted, nothing is cut — and
+    // the whole-guide response names every one.
+    const flood = Array.from({ length: 200 }, (_, i) => ({
+      id: `a-section-id-long-enough-that-two-hundred-never-fit-${i}`,
+      title: `T${i}`,
+      body: `## T${i}\n\nBody.`,
+    }));
+    sectionsNow([...SECTIONS, ...flood]);
+    const counted = await describedAs();
+    expect(counted.length).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    expect(counted).toContain('`introduction`');
+    const shown = (counted.match(/`[^`]+`(?=, |\.$)/g) ?? []).filter((id) => id.startsWith('`a-section-id') || id === '`introduction`' || id === '`access-control`' || id === '`knowledge-graph`');
+    expect(shown.length).toBeGreaterThan(0);
+    expect(shown.length).toBeLessThan(203);
+    expect(counted).toMatch(new RegExp(`and ${203 - shown.length} more, all named under \`sections\` in the whole-guide response\\.$`));
+    // No id is ever cut mid-way: every listed id is one of the guide's.
+    const all = new Set([...SECTIONS, ...flood].map((s) => `\`${s.id}\``));
+    for (const id of shown) expect(all.has(id), id).toBe(true);
+    const whole = (await call()).body as { sections: { id: string }[] };
+    expect(whole.sections.map((s) => s.id)).toEqual([...SECTIONS, ...flood].map((s) => s.id));
+
+    // With the platform's few, the titles are there.
+    sectionsNow(SECTIONS);
+    expect(await describedAs()).toContain('`introduction` (Knowledge base)');
+  });
+
+  it('returns the platform\'s HTML views section on its own, and inside the whole guide', async () => {
+    const { call, registry, sectionsNow } = await serve();
+    const platform = await agentGuideSections(DEFAULT_KB_LAYOUT);
+    sectionsNow([...platform]);
+    const html = platform.find((s) => s.id === 'html-views')!;
+    expect(await call({ section: 'html-views' })).toEqual({
+      status: 200,
+      body: { guide: html.body, section: 'html-views', title: 'HTML views' },
+    });
+    const whole = await call();
+    expect(whole.body.guide).toBe(joinGuideSections(platform));
+    expect(String(whole.body.guide)).toContain('## HTML views');
+    // The description lists it, so an agent knows it can ask for it.
+    const def = (await registry.listExternal()).find((t) => t.name === GET_AGENT_GUIDE_TOOL)!;
+    expect(def.description).toContain('`html-views`');
+  });
+});

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

@@ -0,0 +1,122 @@
+import type { Router, RequestHandler } from 'express';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import { GET_AGENT_GUIDE_TOOL } from '../tool-registry/guide-first.js';
+import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import { AGENT_GUIDE_FILE, joinGuideSections, type AgentGuideSectionsReader } from './agent-guide.js';
+
+export { GET_AGENT_GUIDE_TOOL };
+
+/**
+ * The one tool that returns the guide on its own — whole, or one section by
+ * id. It takes nothing else: the guide is the platform's text for this
+ * deployment, the same for every caller and every branch, and reading it
+ * touches no file — so no `branch`, no `sessionId`, and no access gate. The
+ * other way to the same text is a `read_file` of `AGENTS.md` at the
+ * repository root, which also carries the knowledge base's own `AGENTS.md`
+ * when it has one (see `agent-guide.ts`).
+ *
+ * Registered as a PROVIDER on both surfaces, so the description names the
+ * sections the guide has NOW — a distribution's hook may add its own — and
+ * the in-process agent and an external one are told the same thing to read
+ * first. This is the one tool the catalog does not open with "call
+ * get_agent_guide first" (see `tool-registry/guide-first.ts`): it is what
+ * that sentence points at, and says so itself.
+ */
+export function registerAgentGuideTool(
+  registry: IToolRegistry,
+  router: Router,
+  toolAuth: RequestHandler,
+  toolHandler: ToolHandlerFactory,
+  sections: AgentGuideSectionsReader,
+): void {
+  const build = async (): Promise<UtcpTool> => {
+    const list = await sections();
+    const describe = (sectionList: string) =>
+      "The platform's guide to this knowledge base: its layout, where a new file goes, the rules every file tool " +
+      'shares, access control, skills and tool manuals. ALWAYS call this first and read the guide before you do ' +
+      'anything else in the platform. Returns `{ guide }` as markdown: the whole guide, or one section when ' +
+      '`section` names one. The same text comes back from `read_file` on `' +
+      AGENT_GUIDE_FILE +
+      "` at the KB root, after the knowledge base's own " +
+      AGENT_GUIDE_FILE +
+      ` when it has one. Sections: ${sectionList}.`;
+    // The description stays under the cap WHATEVER a distribution adds, in
+    // three steps: every id with its title; every id alone; as many ids as
+    // fit and a count of the rest. An id a client cut off the end would be a
+    // section an agent cannot ask for — so nothing is ever cut: the one
+    // complete list of sections is `sections` on the whole-guide response,
+    // which the description names when it cannot carry them all itself.
+    const titled = describe(list.map((s) => `\`${s.id}\` (${s.title})`).join(', '));
+    const ids = list.map((s) => `\`${s.id}\``);
+    const counted = (shown: number) =>
+      describe(
+        shown === 0
+          ? `${ids.length}, named under \`sections\` in the whole-guide response`
+          : [...ids.slice(0, shown), `and ${ids.length - shown} more, all named under \`sections\` in the whole-guide response`].join(', '),
+      );
+    let description = titled.length <= TOOL_DESCRIPTION_CAP ? titled : describe(ids.join(', '));
+    for (let shown = ids.length; description.length > TOOL_DESCRIPTION_CAP && shown > 0; shown--) {
+      description = counted(shown - 1);
+    }
+    return toolDef({
+      name: GET_AGENT_GUIDE_TOOL,
+      description,
+      path: `/api/agent/tools/${GET_AGENT_GUIDE_TOOL}`,
+      inputs: {
+        type: 'object',
+        properties: {
+          section: {
+            type: 'string',
+            description:
+              'Optional: the id of one section to read instead of the whole guide (the ids are listed in this ' +
+              'description, and every one under `sections` in the whole-guide response). Omit it for the whole guide.',
+          },
+        },
+        additionalProperties: false,
+      },
+      outputs: {
+        type: 'object',
+        properties: {
+          guide: { type: 'string', description: 'The guide, or the one section asked for, as markdown.' },
+          sections: {
+            type: 'array',
+            description: 'Without `section`: every section of the guide, in order, by id and heading — the complete list.',
+            items: {
+              type: 'object',
+              properties: { id: { type: 'string' }, title: { type: 'string' } },
+              required: ['id', 'title'],
+            },
+          },
+          section: { type: 'string', description: 'With `section`: the id of the section returned.' },
+          title: { type: 'string', description: 'With `section`: its heading.' },
+        },
+        required: ['guide'],
+      },
+      tags: ['workspace'],
+    });
+  };
+  registry.registerInternalTool(build);
+  registry.registerExternalTool(build);
+
+  router.post(
+    `/agent/tools/${GET_AGENT_GUIDE_TOOL}`,
+    toolAuth,
+    toolHandler(async (args) => {
+      const list = await sections();
+      const wanted = typeof args.section === 'string' ? args.section.trim() : '';
+      if (!wanted) return { guide: joinGuideSections(list), sections: list.map((s) => ({ id: s.id, title: s.title })) };
+      const one = list.find((s) => s.id === wanted);
+      if (!one) {
+        throw new ToolError(
+          `The guide has no section "${wanted}". Sections: ${list.map((s) => `\`${s.id}\``).join(', ')}. ` +
+            'Omit `section` for the whole guide.',
+          400,
+        );
+      }
+      return { guide: one.body, section: one.id, title: one.title };
+    }),
+  );
+}

package/src/modules/agent-guide/agent-guide.ts

@@ -0,0 +1,300 @@
+/**
+ * The platform's agent guide: what every agent is told to read before its
+ * first read or change in a knowledge base — the layout, where a new file
+ * goes, the rules every file tool shares, access control, skills and tool
+ * manuals.
+ *
+ * It is TEXT THE CODE OWNS, not a file in the repository. It used to be
+ * written to every protected branch as `AGENTS.md` and refreshed on every
+ * start, which had three costs: a repository that already had an `AGENTS.md`
+ * of its own lost it or had to rename ours; a distribution that wanted to add
+ * to the guide had to fork the whole file and then drifted from every change
+ * made here; and the file sat in git history on every branch, hidden from the
+ * tree by an ignore rule it had to keep writing. Now the guide is composed
+ * from SECTIONS at the moment an agent asks for it — `get_agent_guide`, or a
+ * `read_file` of the guide's name at the repository root — and a distribution
+ * shapes it with a hook that sees the sections and returns the sections it
+ * wants (append, replace or drop by id), so what Hexis says reaches it without
+ * a copy to maintain.
+ *
+ * The sections ship as markdown files in the package's `agent-guide/` folder
+ * (see `assets.ts`), one per section, with the layout placeholders the old
+ * template carried (`{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}`,
+ * `{{agentsFile}}`). ONE section is computed rather than read: the rules every
+ * file tool shares, which the MCP handshake also sends — the same string in
+ * both places, from `shared-file-rules.ts`, so a rule cannot be changed in one
+ * and left stale in the other.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+
+  renderKbLayoutPlaceholders,
+  resolveKbLayout,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { agentGuideDir } from '../../assets.js';
+import { sharedFileRulesSection } from '../agent-instructions/shared-file-rules.js';
+
+/** One section of the guide. */
+export interface AgentGuideSection {
+  /**
+   * Stable id, so a distribution's hook can replace or drop a section by name
+   * and a test can say which one went missing. Core's ids are the
+   * {@link CORE_SECTION_IDS}.
+   */
+  id: string;
+  /**
+   * The section's markdown, heading included (`## …`). May carry the layout
+   * placeholders; they are rendered with the names in effect when the guide is
+   * composed, so a section can name the knowledge folder without knowing what
+   * this deployment calls it.
+   */
+  body: string;
+  /**
+   * The body is FINAL: already rendered, and not to be passed through the
+   * placeholder renderer. Set on the computed shared-rules section, which is
+   * rendered for the layout by the code that builds it; rendering it again
+   * could only misread a folder name it STATES as a placeholder.
+   */
+  literal?: boolean;
+}
+
+/**
+ * A distribution's say over the guide. Called with core's sections, in order,
+ * and the layout in effect; returns the sections the guide is composed from.
+ * Append to the array to add sections, map over it to replace one by id,
+ * filter it to drop one. Called on every composition, so a hook that reads
+ * something live (a feature flag, a setting) is read each time.
+ */
+export type AgentGuideHook = (
+  sections: readonly AgentGuideSection[],
+  layout: Required<KbLayout>,
+) => readonly AgentGuideSection[] | Promise<readonly AgentGuideSection[]>;
+
+/** Composes the guide for the layout in effect — the shape every consumer reads. */
+export type AgentGuideReader = () => Promise<string>;
+
+/** The computed section: the rules every file tool shares. */
+export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
+
+/**
+ * What to do on a knowledge base nobody has written in yet: the section the
+ * `firstRun` note `start_session` answers with points at (see
+ * workspace/first-run.ts, which names it by this constant).
+ */
+export const NEW_KNOWLEDGE_BASE_SECTION_ID = 'new-knowledge-base';
+
+/**
+ * Core's sections, in reading order. Every id but the shared-rules one names
+ * a file in the package's `agent-guide/` folder.
+ */
+export const CORE_SECTION_IDS: readonly string[] = Object.freeze([
+  'introduction',
+  'directory-structure',
+  'where-a-new-file-goes',
+  WORKING_WITH_FILES_SECTION_ID,
+  'access-control',
+  'skills',
+  'tool-manuals',
+  'html-views',
+  'conventions',
+  'finding-things',
+  NEW_KNOWLEDGE_BASE_SECTION_ID,
+]);
+
+/**
+ * The one line that proves a root guide file is the platform's and not the
+ * customer's: the blockquote the packaged guide opened with for as long as
+ * the guide was a file, under every release. Asked for WHERE the header put
+ * it — a blockquote line among the first lines of the file — and not anywhere
+ * in the text: a note of the organisation's own that quotes the platform's
+ * sentence in its body must not read as ours, because the consequence of the
+ * mistake is a deletion. Still read on every start, to take the copies
+ * earlier releases wrote out of the repository (see template-files.step.ts),
+ * and on every read of the guide's name, so a copy still on a draft is not
+ * served twice.
+ */
+const MANAGED_GUIDE_HEADER_LINE = '> **This file is managed by the platform.**';
+
+/** How far down a file the header's blockquote can sit: under the title and a sentence or two, never further. */
+const MANAGED_GUIDE_HEADER_WITHIN_LINES = 12;
+
+/** Whether `text` is a copy of the guide a release wrote to disk, of any vintage. */
+export function isManagedGuide(text: string): boolean {
+  return text
+    .split('\n', MANAGED_GUIDE_HEADER_WITHIN_LINES)
+    .some((line) => line.trimStart().startsWith(MANAGED_GUIDE_HEADER_LINE));
+}
+
+/** The raw section files, read once per process: the package does not change while it runs. */
+let coreSectionFiles: Promise<ReadonlyMap<string, string>> | null = null;
+
+async function readCoreSectionFiles(): Promise<ReadonlyMap<string, string>> {
+  const dir = agentGuideDir();
+  const entries = await Promise.all(
+    CORE_SECTION_IDS.filter((id) => id !== WORKING_WITH_FILES_SECTION_ID).map(
+      // Line endings normalised: a checkout on Windows may carry CRLF, and the
+      // guide is one text with one ending wherever it is served from.
+      async (id) => [id, (await fs.readFile(path.join(dir, `${id}.md`), 'utf8')).replace(/\r\n?/g, '\n')] as const,
+    ),
+  );
+  return new Map(entries);
+}
+
+/**
+ * Core's sections for `layout`: the files, placeholders unrendered, with the
+ * shared-rules section computed and in its place. What a distribution's hook
+ * is handed.
+ */
+export async function coreAgentGuideSections(layout: KbLayout): Promise<AgentGuideSection[]> {
+  coreSectionFiles ??= readCoreSectionFiles();
+  let files: ReadonlyMap<string, string>;
+  try {
+    files = await coreSectionFiles;
+  } catch (err) {
+    // A failed read is not cached: the next composition tries the disk again.
+    coreSectionFiles = null;
+    throw err;
+  }
+  return CORE_SECTION_IDS.map((id) =>
+    id === WORKING_WITH_FILES_SECTION_ID
+      ? { id, body: sharedFileRulesSection(layout), literal: true }
+      : { id, body: files.get(id)! },
+  );
+}
+
+/** What the guide is composed for, beyond the layout. */
+export interface AgentGuideContext {
+  /**
+   * The name of the repository's checkout folder inside a workspace, which
+   * the file tools take paths under (`knowledge-base/` by default). Rendered
+   * into `{{kbDirName}}` so the paths the guide shows are the paths this
+   * deployment's tools report back.
+   */
+  kbDirName?: string;
+}
+
+/** The checkout folder's name when none is given — core's own default. */
+const DEFAULT_KB_DIR_NAME = 'knowledge-base';
+
+/** One section of the guide as an agent reads it: rendered, with the heading's text as its title. */
+export interface RenderedGuideSection {
+  id: string;
+  /** The heading line's text, without its `#`s — what the tool lists the section as. */
+  title: string;
+  /** The section's markdown, heading included, rendered for the layout. */
+  body: string;
+}
+
+/** Composes the guide's sections for the layout in effect — what the guide tool reads. */
+export type AgentGuideSectionsReader = () => Promise<RenderedGuideSection[]>;
+
+/**
+ * The guide's sections as an agent reads them: core's sections through the
+ * distribution's hook (when there is one), rendered for the layout, each
+ * with its title. The whole guide is these joined (see
+ * {@link composeAgentGuide}); `get_agent_guide` also serves one at a time.
+ *
+ * A hook may append, replace and drop sections, with ONE exception: the
+ * shared file rules ({@link WORKING_WITH_FILES_SECTION_ID}) must come back
+ * WITH TEXT IN THEM, as core's or as the hook's own replacement. A client
+ * that drops the handshake instructions has the guide as the only place to
+ * read the rules — a guide without them would leave agents nothing to read.
+ * A hook that drops the section, or hands it back empty, is a composition
+ * error, thrown rather than served. Judged on what would be SERVED — the
+ * rendered, trimmed body — so a replacement of whitespace is caught like a
+ * missing one, rather than passing the check and vanishing with the other
+ * empty sections below.
+ */
+export async function agentGuideSections(
+  layout: KbLayout,
+  hook?: AgentGuideHook,
+  context: AgentGuideContext = {},
+): Promise<RenderedGuideSection[]> {
+  const resolved = resolveKbLayout(layout);
+  const core = await coreAgentGuideSections(resolved);
+  const sections = hook ? await hook(core, resolved) : core;
+  const kbDirName = context.kbDirName?.trim() || DEFAULT_KB_DIR_NAME;
+  const rendered = sections.map((section) => {
+    const body = (
+      section.literal
+        ? section.body
+        : renderKbLayoutPlaceholders(section.body.replaceAll('{{kbDirName}}', () => kbDirName), resolved)
+    ).trim();
+    return { id: section.id, title: titleOf(body, section.id), body };
+  });
+  // Judged over EVERY section under the id — a hook may return the id twice
+  // — on what survives the empty-body filter below: one with text is enough.
+  const rules = rendered.filter((section) => section.id === WORKING_WITH_FILES_SECTION_ID);
+  if (!rules.some((section) => section.body.length > 0)) {
+    throw new Error(
+      `The agent guide hook ${rules.length === 0 ? 'dropped' : 'emptied'} the "${WORKING_WITH_FILES_SECTION_ID}" ` +
+        'section, which every file tool points at. Keep it, or replace it under the same id with the rules in it.',
+    );
+  }
+  return rendered.filter((section) => section.body.length > 0);
+}
+
+/**
+ * The heading's text, or the id when the section opens with no heading. An
+ * ATX heading may close with a run of `#` of its own (`## Custom ##`); that
+ * is a delimiter, not part of the title.
+ */
+function titleOf(body: string, id: string): string {
+  const first = body.split('\n', 1)[0] ?? '';
+  const heading = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/.exec(first);
+  return heading ? heading[1]!.trim() : id;
+}
+
+/**
+ * The guide as an agent reads it whole: the sections joined by blank lines,
+ * ending in one newline.
+ */
+export async function composeAgentGuide(
+  layout: KbLayout,
+  hook?: AgentGuideHook,
+  context: AgentGuideContext = {},
+): Promise<string> {
+  return joinGuideSections(await agentGuideSections(layout, hook, context));
+}
+
+/** The sections as one document, the way `composeAgentGuide` joins them. */
+export function joinGuideSections(sections: readonly RenderedGuideSection[]): string {
+  return `${sections.map((section) => section.body).join('\n\n')}\n`;
+}
+
+/**
+ * What a `read_file` of the guide's name answers when the knowledge base has an
+ * `AGENTS.md` of its own: their text first, whole, then a rule and one line
+ * saying what follows, then the platform's guide. Theirs first because it is
+ * the more specific of the two, and the line between so neither is read as
+ * part of the other.
+ */
+export const PLATFORM_GUIDE_SEPARATOR =
+  "---\n\n_The text above is this knowledge base's own conventions file. The platform's guide follows; `get_agent_guide` returns it on its own._";
+
+export function withPlatformGuideAppended(ownText: string, guide: string): string {
+  // Their text as they wrote it, line endings normalised and the trailing
+  // newlines folded into the one blank line before the separator. Nothing
+  // else is touched: leading indentation and trailing spaces are markdown.
+  const own = ownText.replace(/\r\n?/g, '\n').replace(/\n+$/, '');
+  // A file with nothing in it has nothing to put first, and a separator
+  // above nothing would claim a conventions file that says nothing.
+  if (own.trim().length === 0) return guide;
+  return `${own}\n\n${PLATFORM_GUIDE_SEPARATOR}\n\n${guide}`;
+}
+
+/** The one name the guide is read by: `AGENTS.md` at the repository root, the name coding agents look for. */
+export const AGENT_GUIDE_FILE = 'AGENTS.md';
+
+/**
+ * Whether a repository-relative path is where the guide is read — `AGENTS.md`
+ * at the repository root, exactly spelled, like every platform path. One
+ * name on every deployment: there is no setting for it any more.
+ */
+export function isAgentGuidePath(repoRelativePath: string): boolean {
+  const norm = repoRelativePath.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+  return norm === AGENT_GUIDE_FILE;
+}

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

@@ -0,0 +1,22 @@
+export {
+  AGENT_GUIDE_FILE,
+  CORE_SECTION_IDS,
+  NEW_KNOWLEDGE_BASE_SECTION_ID,
+  PLATFORM_GUIDE_SEPARATOR,
+  WORKING_WITH_FILES_SECTION_ID,
+  agentGuideSections,
+  composeAgentGuide,
+  coreAgentGuideSections,
+  isAgentGuidePath,
+  isManagedGuide,
+  joinGuideSections,
+  withPlatformGuideAppended,
+  type AgentGuideContext,
+  type AgentGuideHook,
+  type AgentGuideReader,
+  type AgentGuideSection,
+  type AgentGuideSectionsReader,
+  type RenderedGuideSection,
+} from './agent-guide.js';
+export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
+export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/guide-first.js';