archgen-mcp 0.1.0 → 0.1.2

package/src/core/guidance.mjs

@@ -0,0 +1,142 @@
+// guidance.mjs — every failure teaches the agent what to do NEXT, in ONE line.
+//
+// WHY THIS FILE EXISTS.
+//
+// An error that only says WHAT FAILED leaves the agent to guess, and a guess
+// that fails the same way is a loop. An agent that called
+// `archgen_refs{action:'read', section:'plan-depth'}` and got
+// "no section 'plan-depth'" had no way to know the slug it was told to use
+// was a shorthand for a longer one — so it burned a round-trip rediscovering
+// the vocabulary, and did it again for the next section.
+//
+// So every archgen failure is ONE line that carries the cause, the fix, and
+// the exact next call:
+//
+//   <cause> — <the fix in a clause>. Next: <the call, ready to paste>
+//
+// The vocabulary is SHARED, so every tool teaches the same way. And where a
+// failure can be prevented rather than explained, it is: the section
+// resolver accepts the shorthand the skill teaches, so the question never
+// comes up.
+//
+// `hint()` adds machine-readable next-step fields to the error DETAILS, so a
+// client can act on them without parsing prose.
+import { invalidInput, notFound } from './errors.mjs';
+
+/**
+ * Compose a ONE-LINE teaching message.
+ *
+ * @param {string} cause what went wrong, in a few words
+ * @param {string} fix the fix, in one clause
+ * @param {string} action the exact next call, ready to paste
+ * @returns {string}
+ */
+export function teach(cause, fix, action) {
+  return `${cause} — ${fix}. Next: ${action}`;
+}
+
+/**
+ * Machine-readable next-step fields, attached to an error's details.
+ *
+ * @param {{action?: string, reason?: string, alternatives?: string[], available?: unknown[]}} spec
+ * @returns {Record<string, unknown>}
+ */
+export function hint(spec) {
+  const out = {};
+  if (spec.action) out.nextAction = spec.action;
+  if (spec.reason) out.reason = spec.reason;
+  if (spec.alternatives?.length) out.alternatives = spec.alternatives;
+  if (spec.available?.length) out.available = spec.available;
+  return out;
+}
+
+/**
+ * "The artifact space does not exist yet."
+ *
+ * `archgen_plan{action:'scaffold'}` is a GENERATOR: it returns the CONTENT
+ * of the files to create, and writes nothing. An agent that assumes otherwise
+ * gets "missing or not a directory" from every artifact tool, and the
+ * natural reading — "the tool is broken" — sends it hunting for a flag that
+ * does not exist.
+ *
+ * @param {string} slug the slug, when known
+ * @param {string} slugDir the path that was looked for
+ */
+export function artifactSpaceMissing(slug, slugDir) {
+  return invalidInput(
+    teach(
+      `no artifact space at ${slugDir}`,
+      'scaffold returns file CONTENT and writes nothing, so write it first',
+      "archgen_plan{action:'scaffold',scope:'LARGE',slug:'<slug>'}",
+    ),
+    hint({ action: "archgen_plan{action:'scaffold',scope:'LARGE',slug:'<slug>'}", reason: 'scaffold returns content; you write it.' }),
+  );
+}
+
+/**
+ * "That section does not exist."
+ *
+ * @param {string} topic the reference topic
+ * @param {string} section the section that was asked for
+ * @param {string[]} available the valid slugs
+ */
+export function noSuchSection(topic, section, available) {
+  return notFound(
+    teach(
+      `no section '${section}' in '${topic}'`,
+      'a prefix of the slug works too, if unambiguous',
+      `archgen_refs{action:'index',topic:'${topic}'}`,
+    ),
+    hint({ action: `archgen_refs{action:'index',topic:'${topic}'}`, reason: 'the index lists every exact slug.', available }),
+  );
+}
+
+/**
+ * "That skill is not installed."
+ *
+ * @param {string} slug the skill slug
+ */
+export function skillNotInstalled(slug) {
+  return invalidInput(
+    teach(
+      `the capability skill '${slug}' is not installed`,
+      'install it before dispatching the worker',
+      `archgen_skills{action:'install',skillId:'${slug}',approve:true}`,
+    ),
+    hint({ action: `archgen_skills{action:'install',skillId:'${slug}',approve:true}`, reason: 'a required skill must be on disk before dispatch.' }),
+  );
+}
+
+/**
+ * "That task id is not in the plan."
+ *
+ * @param {string} taskId the id that was asked for
+ * @param {string[]} available the task ids that exist
+ */
+export function noSuchTask(taskId, available) {
+  return notFound(
+    teach(
+      `no task '${taskId}' in the plan`,
+      'task ids are case-sensitive',
+      "archgen_tasks{action:'list',tasksYaml:'<tasks.yaml>'}",
+    ),
+    hint({ action: "archgen_tasks{action:'list',tasksYaml:'<tasks.yaml>'}", reason: 'the list carries every task id.', available }),
+  );
+}
+
+/**
+ * "That path is outside the project."
+ *
+ * @param {string} path the refused path
+ * @param {string} root the anchor the server is bound to
+ */
+export function outsideProject(path, root) {
+  return invalidInput(
+    teach(
+      `the path is outside the project: ${path}`,
+      'the server is anchored to one root and cannot read or write outside it',
+      `use a path under ${root}`,
+    ),
+    hint({ action: `use a path under ${root}`, reason: 'the anchor is the boundary.' }),
+  );
+}

package/src/core/harness-wiring.mjs

@@ -24,23 +24,103 @@ import { assertNotSymlink, assertWithinRoot, withFileLock, writeFileAtomic } fro
 import { mergeEntry, parseJsonc, removeEntry } from './jsonc-config.mjs';
 import { invalidInput } from './errors.mjs';
 
+/**
+ * The Copilot home: `$COPILOT_HOME`, or `~/.copilot`.
+ *
+ * VS Code reads the Copilot CLI's MCP configuration from here, and the
+ * documentation is explicit that `COPILOT_HOME` REPLACES the default:
+ * "VS Code does not check both locations."
+ *
+ * So a user who sets it has their configuration in ONE place and the other
+ * is ignored. Writing to the ignored one is exactly the "the agent cannot
+ * see the MCP" failure — which is why the config location and the detection
+ * must both follow this same home.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function copilotHome(env = process.env, home = homedir()) {
+  const fromEnv = env.COPILOT_HOME;
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return resolve(fromEnv);
+  return join(home, '.copilot');
+}
+
 /**
  * Detect which harnesses are present in this environment.
  * @param {any} registry the harness-mcp.json content
  * @param {string} projectRoot
  * @param {string} [home]
+ * @param {Record<string, string|undefined>} [env]
  * @returns {Array<{id: string, label: string, atHome: boolean, atProject: boolean, spec: any}>}
  */
-export function detectHarnesses(registry, projectRoot, home = homedir()) {
+export function detectHarnesses(registry, projectRoot, home = homedir(), env = process.env) {
   const found = [];
   for (const [id, h] of Object.entries(registry.harnesses ?? {})) {
-    const atHome = (h.detectHome ?? []).some((m) => existsSync(join(home, m)));
+    const atHome =
+      (h.detectHome ?? []).some((m) => existsSync(join(home, m))) ||
+      // A harness whose configuration lives in a NAMED home (the Copilot
+      // home) is present when that home exists. `COPILOT_HOME` replaces the
+      // default, and the client checks only one of them — so detecting the
+      // default alone would miss a user who set the variable, and wiring the
+      // default alone would write a file the client never reads.
+      namedHomeExists(h, env, home);
     const atProject = (h.detectProject ?? []).some((m) => existsSync(join(projectRoot, m)));
     if (atHome || atProject) found.push({ id, label: h.label, atHome, atProject, spec: h });
   }
   return found;
 }
 
+/** True when the home a harness's configuration lives in exists. */
+function namedHomeExists(harness, env, home) {
+  for (const cfg of Object.values(harness.configs ?? {})) {
+    if (cfg.home === 'copilot' && existsSync(copilotHome(env, home))) return true;
+  }
+  return false;
+}
+
+/**
+ * Where a harness's configuration file lives — and the root it must stay
+ * inside.
+ *
+ * THREE BASES:
+ *   - `home: "copilot"` — the Copilot home (`$COPILOT_HOME`, or
+ *     `~/.copilot`), with the path relative to it.
+ *   - a path starting with `~/` — relative to the home directory.
+ *   - anything else — relative to the project root.
+ *
+ * The path and its containment root come from ONE function on purpose: when
+ * they were computed separately, the root said "the home directory" while
+ * the path said "$COPILOT_HOME" — and the write was then refused by the very
+ * guard meant to protect it.
+ *
+ * @param {any} cfg the registry's config entry
+ * @param {{projectRoot: string, home: string, env?: Record<string, string|undefined>}} ctx
+ * @returns {{path: string, root: string}} the absolute path and its root
+ */
+export function configTargetFor(cfg, ctx) {
+  const env = ctx.env ?? process.env;
+  if (cfg.home === 'copilot') {
+    const base = copilotHome(env, ctx.home);
+    return { path: join(base, cfg.path), root: base };
+  }
+  if (cfg.path.startsWith('~/')) {
+    return { path: expandHome(cfg.path, ctx.home), root: ctx.home };
+  }
+  return { path: join(ctx.projectRoot, cfg.path), root: ctx.projectRoot };
+}
+
+/**
+ * Where a harness's configuration file lives.
+ *
+ * @param {any} cfg the registry's config entry
+ * @param {{projectRoot: string, home: string, env?: Record<string, string|undefined>}} ctx
+ * @returns {string} the absolute path
+ */
+export function configPathFor(cfg, ctx) {
+  return configTargetFor(cfg, ctx).path;
+}
+
 /** Expand a leading `~/` to the home directory. */
 export function expandHome(p, home = homedir()) {
   return p.startsWith('~/') ? join(home, p.slice(2)) : p;
@@ -361,9 +441,10 @@ export function wireServer(opts) {
     fallbackCommand = serverId,
     skipHarnesses = [],
     targets = null,
+    env = process.env,
   } = opts;
 
-  const detected = detectHarnesses(registry, projectRoot, home);
+  const detected = detectHarnesses(registry, projectRoot, home, env);
   // A caller that narrowed the set of harnesses must get exactly that set.
   // The native path honoured the filter and this one did not, so a request
   // for two harnesses wired ten.
@@ -383,9 +464,10 @@ export function wireServer(opts) {
       if (!cfg) continue;
       if (loc === 'global' && !d.atHome) continue;
       if (loc === 'project' && !d.atProject) continue;
-      const absPath = cfg.path.startsWith('~') ? expandHome(cfg.path, home) : join(projectRoot, cfg.path);
+      const target = configTargetFor(cfg, { projectRoot, home, env });
+      const absPath = target.path;
       const entry = buildEntry(entries, npxEntries, cfg.entry, binPath, fallbackCommand);
-      const root = loc === 'global' ? home : projectRoot;
+      const root = target.root;
       const res =
         cfg.format === 'toml'
           ? writeTomlConfig(absPath, serverId, entry, { approved, dryRun, root })
@@ -438,7 +520,7 @@ export function recordWiring(projectRoot, serverId, entries) {
  * @param {'project'|'global'|'both'} [location] which scope to remove
  * @returns {{removed: string[], skipped: string[]}}
  */
-export function removeWiring(projectRoot, serverId, home = homedir(), location = 'both') {
+export function removeWiring(projectRoot, serverId, home = homedir(), location = 'both', env = process.env) {
   const p = join(projectRoot, '.archgen', '.mcp-wiring.json');
   let manifest = null;
   try {
@@ -463,9 +545,11 @@ export function removeWiring(projectRoot, serverId, home = homedir(), location =
       // The manifest is a file ON DISK in the project — repository content.
       // Its paths are therefore untrusted: a clone could ship a manifest
       // naming any file on the machine. A recorded path must resolve inside
-      // the project root or the user's home, or it is refused.
-      if (!pathIsWithin(abs, projectRoot) && !pathIsWithin(abs, home)) {
-        skipped.push(`${abs} (outside the project and home directories)`);
+      // the project root, the user's home, or the Copilot home — those are
+      // the three places a harness's own configuration may live.
+      const allowedRoots = [projectRoot, home, copilotHome(env, home)];
+      if (!allowedRoots.some((r) => pathIsWithin(abs, r))) {
+        skipped.push(`${abs} (outside the project, home and Copilot directories)`);
         continue;
       }
       if (!existsSync(abs)) {

package/src/core/mcp-server-manager.mjs

@@ -112,9 +112,11 @@ export function wireArchgenMcp(opts) {
  * Remove the archgen MCP entries this server wrote.
  * @param {string} projectRoot
  * @param {string} [home]
+ * @param {'project'|'global'|'both'} [location]
+ * @param {Record<string, string|undefined>} [env]
  */
-export function uninstallArchgenMcp(projectRoot, home = homedir(), location = 'both') {
-  return removeWiring(projectRoot, 'archgen', home, location);
+export function uninstallArchgenMcp(projectRoot, home = homedir(), location = 'both', env = process.env) {
+  return removeWiring(projectRoot, 'archgen', home, location, env);
 }
 
 /**

package/src/core/plan-grapher.mjs

@@ -19,6 +19,7 @@ import { parseYaml } from './yaml.mjs';
 import { buildGraph, findCycle, computeWaves, dedupeDependencies, computeQualityStats, GraphError } from './graph.mjs';
 import { resolveSlugInput, ScopeError } from './scope.mjs';
 import { cycle, invalidInput, notFound } from './errors.mjs';
+import { noSuchTask } from './guidance.mjs';
 
 // Whole-graph Mermaid above this node count is refused.
 export const MERMAID_WHOLE_MAX_NODES = 250;
@@ -238,7 +239,7 @@ export function planGraph(input, opts = {}) {
 
   if (node !== null) {
     const t = byId.get(node);
-    if (!t) throw notFound(`no task '${node}' in ${tasksFile}`, { node, file: tasksFile });
+    if (!t) throw noSuchTask(node, uniqueTasks.map((x) => x.id));
     if (mermaid) {
       const up = [...bfsDistances(t.id, prerequisites)].filter(([id]) => id !== t.id).map(([id]) => id).sort();
       const down = [...bfsDistances(t.id, dependents)].filter(([id]) => id !== t.id).map(([id]) => id).sort();

package/src/core/refs.mjs

@@ -23,6 +23,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseMarkdown, buildSections, findSection } from './docs.mjs';
 import { notFound } from './errors.mjs';
+import { noSuchSection } from './guidance.mjs';
 
 /** The reference documents this server serves. */
 export const REF_TOPICS = [
@@ -58,29 +59,61 @@ export function resolveTopic(topic, opts) {
 /**
  * Index one reference topic: its title, purpose and section list.
  *
+ * With `section`, it returns THAT section's entry — the same map, narrowed.
+ * A topic has a dozen sections; an agent that wants one of them should not
+ * have to take the dozen to find it.
+ *
  * @param {string} topic
- * @param {{assetsDir: string, skillDir: string|null}} opts
+ * @param {{assetsDir: string, skillDir: string|null, section?: string|null}} opts
  */
 export function indexTopic(topic, opts) {
   const resolved = resolveTopic(topic, opts);
   if (!resolved) throw notFound(`unknown reference '${topic}'`, { topic, known: REF_TOPICS });
   const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
-  return {
-    topic: resolved.topic,
-    root: resolved.root,
-    title: doc.headings.find((h) => h.level === 1)?.text ?? resolved.topic,
-    sections: buildSections(doc).map((s) => ({
+  const sections = buildSections(doc)
+    // The topic's own H1 is not a SECTION — it is the topic. Listing it
+    // would put "the whole document" at index 0 and make every section map
+    // carry an entry that says nothing.
+    .filter((s) => s.level > 1)
+    .map((s) => ({
       slug: s.slug,
       title: s.title,
       level: s.level,
       line: s.line,
       endLine: s.endLine,
-    })),
+    }));
+  if (opts.section) {
+    const hit = findSection(doc, opts.section);
+    if (!hit) throw noSuchSection(resolved.topic, opts.section, sections.map((s) => s.slug));
+    const one = sections.find((s) => s.slug === hit.slug);
+    return {
+      topic: resolved.topic,
+      root: resolved.root,
+      title: doc.headings.find((h) => h.level === 1)?.text ?? resolved.topic,
+      section: one,
+      sections: [one],
+    };
+  }
+  return {
+    topic: resolved.topic,
+    root: resolved.root,
+    title: doc.headings.find((h) => h.level === 1)?.text ?? resolved.topic,
+    sections,
   };
 }
 
 /**
- * Read one section (or the whole topic).
+ * Read one section (or the topic's section INDEX).
+ *
+ * WHY THE DEFAULT IS THE INDEX: a whole topic is ~11 KB of English, and the
+ * whole design of this module is that the agent reads a SECTION. Returning
+ * the entire topic when the caller named no section made the expensive
+ * answer the default — so an agent that forgot the section paid for the
+ * whole protocol instead of getting the map that would have told it which
+ * section it needed.
+ *
+ * So: no section → the INDEX (the map) plus the exact next call. The whole
+ * topic is `section: '*'` — deliberate, never the default.
  *
  * @param {string} topic
  * @param {{assetsDir: string, skillDir: string|null, section?: string|null}} opts
@@ -88,27 +121,36 @@ export function indexTopic(topic, opts) {
 export function readTopic(topic, opts) {
   const resolved = resolveTopic(topic, opts);
   if (!resolved) throw notFound(`unknown reference '${topic}'`, { topic, known: REF_TOPICS });
-  const text = readFileSync(resolved.path, 'utf8');
-  const doc = parseMarkdown(text);
 
-  if (!opts.section) {
+  // The whole topic — asked for explicitly.
+  if (opts.section === '*') {
+    const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
     return {
       topic: resolved.topic,
       root: resolved.root,
       section: null,
+      whole: true,
       text: doc.lines.join('\n'),
       lines: doc.lines.length,
     };
   }
 
+  // No section named: the MAP, not the text.
+  if (!opts.section) {
+    const indexed = indexTopic(topic, opts);
+    return {
+      ...indexed,
+      whole: false,
+      next: `archgen_refs{action:'read',topic:'${resolved.topic}',section:'<the section you need>'}`,
+      hint: 'read ONE section — a whole topic is a map plus the text you did not ask for.',
+    };
+  }
+
+  const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
   const section = findSection(doc, opts.section);
   if (!section) {
     const available = buildSections(doc).map((s) => s.slug);
-    throw notFound(`no section '${opts.section}' in '${resolved.topic}'`, {
-      topic: resolved.topic,
-      section: opts.section,
-      available,
-    });
+    throw noSuchSection(resolved.topic, opts.section, available);
   }
   return {
     topic: resolved.topic,
@@ -139,14 +181,34 @@ export function searchTopic(topic, token, opts) {
   // Whole-word: a hit must not be glued to word characters on either side.
   const re = new RegExp(`(?<![A-Za-z0-9_])${esc}(?![A-Za-z0-9_])`, 'i');
 
+  // The sections OVERLAP: a parent section's body runs to the next heading at
+  // the same or shallower level, so it CONTAINS its children. Reporting a hit
+  // once per containing section therefore delivered the same line three times
+  // for a three-level nesting — the agent paid for the same sentence three
+  // times to learn one fact.
+  //
+  // So every hit is reported ONCE, under the DEEPEST section that contains
+  // it: the most specific place the line actually lives.
+  const sections = buildSections(doc).filter((s) => s.level > 1);
+  const ownerOf = (line) => {
+    let owner = null;
+    for (const s of sections) {
+      if (line < s.line || line > s.endLine) continue;
+      if (owner === null || s.level > owner.level) owner = s;
+    }
+    return owner;
+  };
+
   const hits = [];
-  for (const section of buildSections(doc)) {
+  for (const section of sections) {
     const bodyLines = doc.lines.slice(section.line - 1, section.endLine);
     const matches = [];
     for (let i = 0; i < bodyLines.length; i++) {
-      if (re.test(bodyLines[i])) {
-        matches.push({ line: section.line + i, text: bodyLines[i].trim().slice(0, 200) });
-      }
+      if (!re.test(bodyLines[i])) continue;
+      const line = section.line + i;
+      const owner = ownerOf(line);
+      if (!owner || owner.slug !== section.slug) continue; // its deepest owner reports it
+      matches.push({ line, text: bodyLines[i].trim().slice(0, 200) });
     }
     if (matches.length) {
       hits.push({
@@ -160,7 +222,15 @@ export function searchTopic(topic, token, opts) {
       });
     }
   }
-  return { topic: resolved.topic, root: resolved.root, token, sections: hits, sectionCount: hits.length };
+  return {
+    topic: resolved.topic,
+    root: resolved.root,
+    token,
+    sections: hits,
+    sectionCount: hits.length,
+    // The distinct lines behind those hits — reported once, counted once.
+    matchCount: hits.reduce((n, h) => n + h.occurrences, 0),
+  };
 }
 
 /**

package/src/core/scaffold.mjs

@@ -81,6 +81,12 @@ export function buildScaffold(ladder, scopeClass, opts = {}) {
   return {
     scopeClass: key,
     label: spec.label,
+    // THIS TOOL WRITES NOTHING. It returns the CONTENT of every file the
+    // scope class needs, and the caller writes them. An agent that assumes
+    // otherwise gets "missing or not a directory" from every artifact tool
+    // and reads it as a broken tool rather than an unwritten plan.
+    writes: false,
+    writeThese: artifacts.map((a) => a.path),
     intentDefaults: spec.intentDefaults ?? [],
     roundCap: spec.roundCap ?? null,
     artifacts,

package/src/core/worker-contract.mjs

@@ -30,7 +30,8 @@ import { dirname, join } from 'node:path';
 import { parseYaml } from './yaml.mjs';
 import { buildGraph, GraphError } from './graph.mjs';
 import { skillDirective } from './skill-manager.mjs';
-import { invalidInput, notFound } from './errors.mjs';
+import { invalidInput } from './errors.mjs';
+import { noSuchTask } from './guidance.mjs';
 
 /**
  * Assemble the worker prompt for one task.
@@ -64,7 +65,7 @@ export function buildWorkerContract(opts) {
   }
   const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
   const task = tasks.find((t) => t?.id === taskId);
-  if (!task) throw notFound(`task '${taskId}' not found in ${tasksYaml}`, { taskId, file: tasksYaml });
+  if (!task) throw noSuchTask(taskId, tasks.map((t) => t?.id).filter(Boolean));
 
   // The dependency neighbourhood — what must exist BEFORE this task, and what
   // waits on it. Derived from depends_on, never hand-labelled.

package/src/envelope.mjs

@@ -42,7 +42,12 @@ export function fail(e, meta = {}) {
 export async function guard(body, ctx, args) {
   try {
     const data = await body(ctx, args);
-    const meta = typeof data === 'object' && data !== null && data.__meta ? data.__meta : ctx.meta();
+    // A tool that carries its own meta (the map to the rest of the data)
+    // EXTENDS the envelope's meta — it never replaces it. The envelope's
+    // meta is the contract (server version, skill version, project root,
+    // warnings); the tool's meta is the map to whatever it did not send.
+    const own = typeof data === 'object' && data !== null && data.__meta ? data.__meta : null;
+    const meta = own ? { ...ctx.meta(), ...own } : ctx.meta();
     const payload = typeof data === 'object' && data !== null && data.__meta ? data.data : data;
     return ok(payload, meta);
   } catch (e) {
@@ -63,3 +68,95 @@ export function toToolResult(envelope) {
     ...(envelope.ok ? {} : { isError: true }),
   };
 }
+
+// ── collection projection ───────────────────────────────────────────────────
+//
+// WHY: a tool that answers "give me everything in this collection" makes the
+// agent pay for the whole collection every time it needs ONE item — and the
+// only way to get one item is to take the whole collection and pick from it.
+// That is the wrong default for both sides: the server sends text nobody
+// asked for, and the agent pays for it in context.
+//
+// The fix is not a smaller cap — a cap silently truncates, and the agent
+// cannot tell what it missed. It is a SELECTOR plus a MAP TO THE REST: every
+// collection-shaped answer can be narrowed to one item, and every answer says
+// what else exists and exactly how to fetch it. The agent fetches; it never
+// receives a dump.
+
+/**
+ * The default bound on a collection.
+ *
+ * It exists so a LARGE project cannot dump itself: a 500-task plan, a
+ * 250-node graph, a 200-file artifact tree. The bound is the CALLER's to
+ * raise (`limit`), and every answer says how many items exist and exactly
+ * which call returns the next slice — so a bound never hides data, it only
+ * makes the agent ask for it.
+ */
+export const DEFAULT_LIMIT = 50;
+
+/**
+ * Narrow a collection to what the caller asked for, and report what is left.
+ *
+ * `limit` is the caller's bound, not the server's: a caller that needs the
+ * whole set asks for it (`limit: null` means no bound). The default is
+ * finite so a huge collection is never dumped — and the report says exactly
+ * how many remain and which call gets the next slice.
+ *
+ * @param {any[]} items
+ * @param {{limit?: number|null, offset?: number|null, next?: string|null}} [opts]
+ * @returns {{items: any[], total: number, returned: number, offset: number, limit: number|null, truncated: boolean, next: string|null}}
+ */
+export function project(items, opts = {}) {
+  const all = Array.isArray(items) ? items : [];
+  const offset = Math.max(0, Number(opts.offset ?? 0) || 0);
+  const rawLimit = opts.limit === undefined ? DEFAULT_LIMIT : opts.limit;
+  const limit = rawLimit === null ? null : Math.max(0, Math.trunc(Number(rawLimit) || 0));
+  const slice = limit === null ? all.slice(offset) : all.slice(offset, offset + limit);
+  const truncated = offset + slice.length < all.length;
+  return {
+    items: slice,
+    total: all.length,
+    returned: slice.length,
+    offset,
+    limit,
+    truncated,
+    // The exact next call — not a hint, not a cursor the agent has to build.
+    next: truncated ? (opts.next ?? null) : null,
+  };
+}
+
+/**
+ * The uniform "what else is there" block.
+ *
+ * Every collection-shaped answer carries it, so the agent always knows that
+ * more exists and exactly how to get it — without the server having sent any
+ * of it.
+ *
+ * @param {{total?: number, returned?: number, available?: object, more?: string|null, next?: string|null}} info
+ * @returns {object}
+ */
+export function moreMeta(info = {}) {
+  const meta = {};
+  if (info.total !== undefined) meta.total = info.total;
+  if (info.returned !== undefined) meta.returned = info.returned;
+  if (info.available && Object.keys(info.available).length) meta.available = info.available;
+  if (info.more) meta.more = info.more;
+  if (info.next) meta.next = info.next;
+  return meta;
+}
+
+/**
+ * Attach meta to a payload.
+ *
+ * The envelope already understands this shape (`__meta` is lifted out of the
+ * data), so a tool can add the map to the rest without knowing anything
+ * about the envelope.
+ *
+ * @param {unknown} data
+ * @param {object} meta
+ * @returns {{data: unknown, __meta: object}}
+ */
+export function withMeta(data, meta) {
+  return { data, __meta: meta };
+}
+