@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/context/instructions.mjs

@@ -0,0 +1,327 @@
+/**
+ * lib/engine/context/instructions.mjs — the instruction files a run reads.
+ *
+ * Every file found is included, in this order, each under a header naming it:
+ *
+ *   1. managed   the organisation-managed CLAUDE.md
+ *                (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS,
+ *                /etc/claude-code/CLAUDE.md on Linux)
+ *   2. user      ~/.claude/CLAUDE.md          ($CLAUDE_CONFIG_DIR/CLAUDE.md)
+ *   3. then for each directory from the filesystem root down to the working
+ *      directory, in this order at each level:
+ *        CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, COHORT.md, AGENTS.md
+ *   rules        every `*.md` under ~/.claude/rules (after the user file) and
+ *                <cwd>/.claude/rules (after the last level), recursively, in
+ *                path order. A rule whose frontmatter has `paths:` (globs,
+ *                relative to cwd) is not loaded here: it is returned in
+ *                `conditionalRules` and injected when a matching file is
+ *                touched (lazy-instructions.mjs), as are CLAUDE.md files in
+ *                directories below cwd.
+ *   4. memory    the project's auto-memory index,
+ *                ~/.claude/projects/<cwd with every non-alphanumeric as "->/memory/MEMORY.md,
+ *                capped at its first 200 lines and 25 KB
+ *
+ * Nothing shadows anything: a global AGENTS.md does not hide ~/.claude/CLAUDE.md
+ * (where maestro writes an agent's identity block), and COHORT.md sits beside
+ * CLAUDE.md rather than replacing it. The same file reached twice (a home
+ * directory that is also an ancestor of cwd) is included once.
+ *
+ * Imports: `@path` in a file's text (outside code spans and fenced blocks)
+ * includes that file after the line that names it. Relative paths resolve
+ * against the importing file's directory; `~/` against the home directory.
+ * Imports nest to a depth of 5; a file already on the import chain, or already
+ * included, is not included again. A token that does not name an existing file
+ * is left as text (it is probably an @-mention).
+ *
+ * The text is deterministic for a given set of files, so it can sit in the
+ * cached prefix of the system prompt.
+ *
+ * All reads go through the injected `readFile` / `isFile`.
+ *
+ * @module lib/engine/context/instructions
+ */
+
+import path from "node:path";
+import { parseSkillFile } from "../skills/index.mjs";
+
+export const RULES_DIR = path.join(".claude", "rules");
+const MAX_RULE_DEPTH = 8;
+
+export const FILES_PER_LEVEL = Object.freeze(["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md", "COHORT.md", "AGENTS.md"]);
+export const MAX_IMPORT_DEPTH = 5;
+export const MEMORY_MAX_LINES = 200;
+export const MEMORY_MAX_BYTES = 25_000;
+
+/** @param {string} platform */
+export function defaultManagedInstructionsPath(platform) {
+  if (platform === "darwin") return "/Library/Application Support/ClaudeCode/CLAUDE.md";
+  if (platform === "linux") return "/etc/claude-code/CLAUDE.md";
+  return null;
+}
+
+/**
+ * Directories from the filesystem root down to `cwd`, inclusive.
+ * @param {string} cwd
+ */
+export function ancestorDirs(cwd) {
+  const abs = path.resolve(cwd);
+  const dirs = [];
+  let cur = abs;
+  for (;;) {
+    dirs.unshift(cur);
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return dirs;
+}
+
+/** @param {string} name */
+function scopeOf(name) {
+  return name === "CLAUDE.local.md" ? "local" : "project";
+}
+
+/**
+ * @param {{cwd:string, userDir:string|null, managedPath?:string|null}} p
+ * @returns {Array<{path:string, scope:'managed'|'user'|'project'|'local'}>}
+ */
+export function instructionCandidates({ cwd, userDir, managedPath = null }) {
+  const out = [];
+  if (managedPath) out.push({ path: managedPath, scope: /** @type const */ ("managed") });
+  if (userDir) out.push({ path: path.join(userDir, "CLAUDE.md"), scope: /** @type const */ ("user") });
+  for (const dir of ancestorDirs(cwd)) {
+    for (const name of FILES_PER_LEVEL) out.push({ path: path.join(dir, name), scope: scopeOf(name) });
+  }
+  return /** @type any */ (out);
+}
+
+/**
+ * The @path tokens of a text, outside fenced blocks and inline code.
+ * @param {string} text
+ * @returns {Array<{line:number, target:string}>}
+ */
+export function findImports(text) {
+  const found = [];
+  let fenced = false;
+  const lines = String(text).split("\n");
+  lines.forEach((line, i) => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) return;
+    const visible = line.replace(/`[^`]*`/g, (m) => " ".repeat(m.length));
+    const re = /(^|\s)@((?:~\/|\.{1,2}\/|\/)?[^\s`'"()<>]+)/g;
+    let m;
+    while ((m = re.exec(visible)) !== null) {
+      const target = m[2].replace(/[.,;:!?]+$/, "");
+      if (target !== "") found.push({ line: i, target });
+    }
+  });
+  return found;
+}
+
+/**
+ * @param {string} target @param {{baseDir:string, homedir:string|null}} o
+ */
+export function resolveImportPath(target, { baseDir, homedir }) {
+  if (target.startsWith("~/")) return homedir ? path.join(homedir, target.slice(2)) : null;
+  return path.resolve(baseDir, target);
+}
+
+/**
+ * @param {string} text
+ * @param {object} o
+ * @param {string} o.file              the file this text came from
+ * @param {string|null} o.homedir
+ * @param {(p:string)=>string} o.readFile
+ * @param {(p:string)=>boolean} o.isFile
+ * @param {Set<string>} o.included     every file already in the output (mutated)
+ * @param {string[]} [o.chain]         the import chain above this file
+ * @returns {string}
+ */
+export function expandImports(text, o) {
+  const chain = [...(o.chain ?? []), o.file];
+  const depth = chain.length - 1;
+  const imports = findImports(text);
+  if (imports.length === 0 || depth >= MAX_IMPORT_DEPTH) return text;
+  const byLine = new Map();
+  for (const imp of imports) {
+    const abs = resolveImportPath(imp.target, { baseDir: path.dirname(o.file), homedir: o.homedir });
+    if (!abs || chain.includes(abs) || o.included.has(abs) || !o.isFile(abs)) continue;
+    let body;
+    try {
+      body = o.readFile(abs);
+    } catch {
+      continue; // unreadable: leave the token as written
+    }
+    o.included.add(abs);
+    const expanded = expandImports(body, { ...o, file: abs, chain });
+    const list = byLine.get(imp.line) ?? [];
+    list.push(`[imported from ${abs}]\n${expanded.trimEnd()}\n[end of ${abs}]`);
+    byLine.set(imp.line, list);
+  }
+  if (byLine.size === 0) return text;
+  return String(text)
+    .split("\n")
+    .flatMap((line, i) => (byLine.has(i) ? [line, ...byLine.get(i)] : [line]))
+    .join("\n");
+}
+
+/**
+ * @param {{cwd:string, userDir:string|null}} p
+ */
+export function memoryIndexPath({ cwd, userDir }) {
+  if (!userDir) return null;
+  return path.join(userDir, "projects", path.resolve(cwd).replace(/[^A-Za-z0-9]/g, "-"), "memory", "MEMORY.md");
+}
+
+/** First 200 lines, then at most 25 KB (cut at a line boundary where possible). @param {string} text */
+export function capMemory(text) {
+  const lines = String(text).split("\n");
+  let out = lines.slice(0, MEMORY_MAX_LINES).join("\n");
+  const truncatedLines = lines.length > MEMORY_MAX_LINES;
+  let truncatedBytes = false;
+  if (Buffer.byteLength(out, "utf8") > MEMORY_MAX_BYTES) {
+    truncatedBytes = true;
+    let buf = Buffer.from(out, "utf8").subarray(0, MEMORY_MAX_BYTES).toString("utf8");
+    buf = buf.replace(/�$/, "");
+    const nl = buf.lastIndexOf("\n");
+    out = nl > 0 ? buf.slice(0, nl) : buf;
+  }
+  return { text: out, truncated: truncatedLines || truncatedBytes };
+}
+
+/**
+ * Every `.md` file under a rules directory, recursively, sorted by path.
+ * @param {string} dir @param {{readdir?:(p:string)=>string[], isDir?:(p:string)=>boolean, isFile:(p:string)=>boolean}} fs
+ */
+export function listRuleFiles(dir, fs) {
+  if (!fs.readdir || !fs.isDir || !fs.isDir(dir)) return [];
+  const out = [];
+  const walk = (/** @type string */ d, /** @type number */ depth) => {
+    let names;
+    try {
+      names = /** @type {(p:string)=>string[]} */ (fs.readdir)(d).sort();
+    } catch {
+      return;
+    }
+    for (const n of names) {
+      const full = path.join(d, n);
+      if (/** @type {(p:string)=>boolean} */ (fs.isDir)(full)) {
+        if (depth < MAX_RULE_DEPTH) walk(full, depth + 1);
+      } else if (n.endsWith(".md") && fs.isFile(full)) out.push(full);
+    }
+  };
+  walk(dir, 0);
+  return out;
+}
+
+/**
+ * A rule file's `paths` frontmatter (string or list, comma separated) and body.
+ * @param {string} text @returns {{patterns:string[], body:string}}
+ */
+export function parseRule(text) {
+  const { frontmatter, body } = parseSkillFile(text);
+  const raw = frontmatter.paths;
+  const list = Array.isArray(raw) ? raw.map(String) : typeof raw === "string" ? raw.split(",") : [];
+  return { patterns: list.map((s) => s.trim().replace(/^["']|["']$/g, "").trim()).filter(Boolean), body };
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.cwd
+ * @param {string|null} p.homedir
+ * @param {string|null} p.userDir
+ * @param {string|null} [p.managedPath]
+ * @param {(p:string)=>string} p.readFile
+ * @param {(p:string)=>boolean} p.isFile
+ * @param {(p:string)=>string} [p.realpath]
+ * @param {(p:string)=>string[]} [p.readdir]  with isDir: enables .claude/rules
+ * @param {(p:string)=>boolean} [p.isDir]
+ */
+export function loadInstructions({ cwd, homedir, userDir, managedPath = null, readFile, isFile, realpath = (p) => p, readdir, isDir }) {
+  const included = new Set();
+  const seenReal = new Set();
+  /** @type {Array<{path:string, scope:string, content:string}>} */
+  const files = [];
+  const errors = [];
+  /** @type {Array<{path:string, patterns:string[], content:string}>} */
+  const conditionalRules = [];
+  const addRules = (/** @type string */ dir, /** @type string */ scope) => {
+    for (const file of listRuleFiles(dir, { readdir, isDir, isFile })) {
+      let real;
+      try {
+        real = realpath(file);
+      } catch {
+        real = file;
+      }
+      // A rule already pulled in by an @import (or reached twice) is included once.
+      if (seenReal.has(real) || included.has(file)) continue;
+      seenReal.add(real);
+      let text;
+      try {
+        text = readFile(file);
+      } catch (e) {
+        errors.push(`${file}: ${e instanceof Error ? e.message : e}`);
+        continue;
+      }
+      included.add(file);
+      const { patterns, body } = parseRule(text);
+      const content = expandImports(body, { file, homedir, readFile, isFile, included });
+      if (patterns.length > 0) conditionalRules.push({ path: file, patterns, content });
+      else files.push({ path: file, scope, content });
+    }
+  };
+  let userRulesDone = false;
+  for (const c of instructionCandidates({ cwd, userDir, managedPath })) {
+    if (!userRulesDone && c.scope !== "managed" && c.scope !== "user") {
+      userRulesDone = true;
+      if (userDir) addRules(path.join(userDir, "rules"), "user rule");
+    }
+    if (!isFile(c.path)) continue;
+    let real;
+    try {
+      real = realpath(c.path);
+    } catch {
+      real = c.path;
+    }
+    if (seenReal.has(real) || included.has(c.path)) continue;
+    seenReal.add(real);
+    let text;
+    try {
+      text = readFile(c.path);
+    } catch (e) {
+      errors.push(`${c.path}: ${e instanceof Error ? e.message : e}`);
+      continue;
+    }
+    included.add(c.path);
+    files.push({ path: c.path, scope: c.scope, content: expandImports(text, { file: c.path, homedir, readFile, isFile, included }) });
+  }
+  addRules(path.join(cwd, RULES_DIR), "project rule");
+  let memory = null;
+  const mem = memoryIndexPath({ cwd, userDir });
+  if (mem && isFile(mem)) {
+    try {
+      const capped = capMemory(readFile(mem));
+      memory = { path: mem, content: capped.text, truncated: capped.truncated };
+    } catch (e) {
+      errors.push(`${mem}: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+  return { files, memory, errors, conditionalRules };
+}
+
+/**
+ * The system-prompt block (pure). Null when nothing was found.
+ * @param {{files:Array<{path:string, scope:string, content:string}>, memory:{path:string, content:string, truncated?:boolean}|null}} loaded
+ */
+export function formatInstructions({ files, memory }) {
+  if (files.length === 0 && !memory) return null;
+  const parts = ["Instructions for this work follow, from the most general file to the most specific. Where they conflict, the more specific file wins."];
+  for (const f of files) parts.push(`## ${f.path} (${f.scope})\n\n${f.content.trim()}`);
+  if (memory) {
+    parts.push(`## ${memory.path} (memory index${memory.truncated ? ", truncated" : ""})\n\n${memory.content.trim()}`);
+  }
+  return parts.join("\n\n");
+}

package/lib/engine/context/lazy-instructions.mjs

@@ -0,0 +1,169 @@
+/**
+ * lib/engine/context/lazy-instructions.mjs — instructions found as the run moves (CF-21).
+ *
+ * At startup the engine reads the instruction files from the filesystem root
+ * down to the working directory (instructions.mjs). A repository often keeps
+ * more specific files further down — `packages/api/CLAUDE.md` — and
+ * `.claude/rules/*.md` files can say which paths they apply to (`paths:`
+ * frontmatter). Loading all of those up front would spend context on parts
+ * of the tree the run never touches, so they are loaded LAZILY:
+ *
+ *   · when Read, Edit, Write, MultiEdit or NotebookEdit touches a file below
+ *     the working directory, every instruction file (CLAUDE.md,
+ *     .claude/CLAUDE.md, CLAUDE.local.md, COHORT.md, AGENTS.md) in each
+ *     directory from just below cwd down to that file's directory is read,
+ *     with its @imports;
+ *   · a path-scoped rule is read when a touched file matches one of its globs
+ *     (relative to the working directory);
+ *   · each file is injected ONCE per run, as text appended to the message that
+ *     carries the tool results — never into the system prompt, whose bytes are
+ *     the cached prefix.
+ *
+ * The loader remembers what it injected, so compaction can carry it forward.
+ *
+ * @module lib/engine/context/lazy-instructions
+ */
+
+import path from "node:path";
+import { FILES_PER_LEVEL, expandImports } from "./instructions.mjs";
+
+export const TOUCH_TOOLS = Object.freeze(new Set(["Read", "Edit", "Write", "MultiEdit", "NotebookEdit"]));
+
+/**
+ * The absolute file a tool call touches, or null.
+ * @param {string} toolName @param {any} input @param {string} cwd
+ */
+export function touchedPath(toolName, input, cwd) {
+  if (!TOUCH_TOOLS.has(toolName) || !input || typeof input !== "object") return null;
+  const p = input.file_path ?? input.notebook_path;
+  if (typeof p !== "string" || p === "") return null;
+  return path.resolve(cwd, p);
+}
+
+/**
+ * Instruction files for a touched file: directories strictly below `cwd` down
+ * to the file's directory, outermost first. Empty for a file outside cwd.
+ * @param {{cwd:string, file:string}} p
+ */
+export function nestedInstructionCandidates({ cwd, file }) {
+  const root = path.resolve(cwd);
+  const dir = path.dirname(path.resolve(file));
+  const rel = path.relative(root, dir);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return [];
+  const out = [];
+  let cur = root;
+  for (const part of rel.split(path.sep)) {
+    cur = path.join(cur, part);
+    for (const name of FILES_PER_LEVEL) out.push(path.join(cur, name));
+  }
+  return out;
+}
+
+/**
+ * A glob as a regular expression over a forward-slash relative path:
+ * `**` any depth, `*` within a segment, `?` one character, `{a,b}` either.
+ * A pattern with no slash matches the file name at any depth.
+ * @param {string} glob
+ */
+export function globToRegExp(glob) {
+  let g = String(glob).trim().replace(/^\.\//, "");
+  if (!g.includes("/")) g = `**/${g}`;
+  let re = "";
+  for (let i = 0; i < g.length; i++) {
+    const ch = g[i];
+    if (ch === "*") {
+      if (g[i + 1] === "*") {
+        const slash = g[i + 2] === "/";
+        re += slash ? "(?:.*/)?" : ".*";
+        i += slash ? 2 : 1;
+      } else re += "[^/]*";
+    } else if (ch === "?") re += "[^/]";
+    else if (ch === "{") {
+      const end = g.indexOf("}", i);
+      if (end === -1) re += "\\{";
+      else {
+        re += `(?:${g.slice(i + 1, end).split(",").map((s) => s.replace(/[.+^$()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")).join("|")})`;
+        i = end;
+      }
+    } else re += ch.replace(/[.+^$()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * @typedef {{path:string, patterns:string[], content:string}} ConditionalRule
+ */
+
+/**
+ * @param {object} p
+ * @param {string} p.cwd
+ * @param {string|null} p.homedir
+ * @param {(p:string)=>string} p.readFile
+ * @param {(p:string)=>boolean} p.isFile
+ * @param {(p:string)=>string} [p.realpath]
+ * @param {string[]} [p.loaded]               files already in the system prompt
+ * @param {ConditionalRule[]} [p.conditionalRules]
+ */
+export function createLazyInstructions({ cwd, homedir, readFile, isFile, realpath = (x) => x, loaded = [], conditionalRules = [] }) {
+  const real = (/** @type string */ p) => {
+    try {
+      return realpath(p);
+    } catch {
+      return p;
+    }
+  };
+  const seen = new Set(loaded.map(real));
+  const included = new Set(loaded);
+  /** @type {Array<{path:string, content:string, reason:string}>} */
+  const injected = [];
+  const rules = conditionalRules.map((r) => ({ ...r, res: r.patterns.map(globToRegExp) }));
+
+  return {
+    /**
+     * Instruction files to inject because this file was touched (each once).
+     * @param {string} file absolute
+     * @returns {Array<{path:string, content:string, reason:string}>}
+     */
+    touch(file) {
+      const out = [];
+      for (const candidate of nestedInstructionCandidates({ cwd, file })) {
+        if (!isFile(candidate)) continue;
+        const r = real(candidate);
+        if (seen.has(r)) continue;
+        seen.add(r);
+        let text;
+        try {
+          text = readFile(candidate);
+        } catch {
+          continue;
+        }
+        included.add(candidate);
+        const content = expandImports(text, { file: candidate, homedir, readFile, isFile, included });
+        out.push({ path: candidate, content, reason: `it applies to files under ${path.dirname(candidate)}` });
+      }
+      const rel = path.relative(path.resolve(cwd), path.resolve(file)).split(path.sep).join("/");
+      if (!rel.startsWith("..") && !path.isAbsolute(rel)) {
+        for (const rule of rules) {
+          if (seen.has(real(rule.path)) || !rule.res.some((re) => re.test(rel))) continue;
+          seen.add(real(rule.path));
+          out.push({ path: rule.path, content: rule.content, reason: `its paths (${rule.patterns.join(", ")}) match ${rel}` });
+        }
+      }
+      injected.push(...out);
+      return out;
+    },
+    /** Everything injected so far, in order. */
+    injected: () => injected.map(({ path: p, content }) => ({ path: p, content })),
+  };
+}
+
+/**
+ * The text block appended after tool results (pure).
+ * @param {Array<{path:string, content:string, reason:string}>} entries
+ */
+export function formatLazyInstructions(entries) {
+  if (entries.length === 0) return null;
+  return entries
+    .map((e) => `Instructions from ${e.path} now apply (${e.reason}). Follow them alongside the instructions you already have; where they conflict, these more specific ones win.\n\n${e.content.trim()}`)
+    .join("\n\n");
+}

package/lib/engine/context/manager.mjs

@@ -0,0 +1,182 @@
+/**
+ * lib/engine/context/manager.mjs — what the loop asks at every turn boundary.
+ *
+ * The loop (loop.mjs `p.context`) calls three hooks:
+ *
+ *   beforeTurn   before each model request:
+ *                  1. servers that announced a tool-list change are re-listed
+ *                     and the tool set rebuilt (never mid-turn);
+ *                  2. queued input is drained — a stream-json
+ *                     `{type:"control", subtype:"compact"}` requests manual
+ *                     compaction; queued user messages are appended;
+ *                  3. images leave all but the most recent image-carrying
+ *                     tool results (images.mjs);
+ *                     the request is measured and projected (budget.mjs);
+ *                     at the threshold — or on a manual request — compaction
+ *                     runs (compaction.mjs) and the history is replaced;
+ *                  4. the definitions to send are computed: the fixed tools and
+ *                     loaded deferred tools, canonical and in stable order.
+ *   observe      after each model request: the provider's input-token count
+ *                calibrates the estimator.
+ *   afterTools   after each tool batch: a deferred tool called by name is
+ *                loaded; files touched by Read/Edit/Write bring in the
+ *                instruction files that apply to them (lazy-instructions.mjs),
+ *                returned as a text block appended to the tool results.
+ *
+ * Automatic compaction does not repeat on the next turn if it could not get
+ * under the limit: it waits until the projection has grown by a tenth of the
+ * window since, so a history that cannot shrink further is not re-summarised
+ * every turn.
+ *
+ * @module lib/engine/context/manager
+ */
+
+import { measureRequest, initialCalibration, calibrate, projectTokens, compactionLimit, charsForTokens, reportedInputTokens } from "./budget.mjs";
+import { stableToolDefinitions } from "./cache.mjs";
+import { runCompaction } from "./compaction.mjs";
+import { touchedPath, formatLazyInstructions } from "./lazy-instructions.mjs";
+import { pruneOldImages, DEFAULT_KEEP_IMAGE_RESULTS } from "./images.mjs";
+
+/**
+ * @param {object} p
+ * @param {import('./budget.mjs').ContextConfig} p.config
+ * @param {string} p.cwd
+ * @param {(turn:{system:string, messages:any[], tools:any[], signal?:AbortSignal})=>Promise<any>} p.summarise  same wire, same tier
+ * @param {any[]} p.tools  every callable tool, in stable order
+ * @param {ReturnType<typeof import('../tools/toolsearch.mjs').createDeferredTools>|null} [p.deferred]
+ * @param {{preCompact:(o:{trigger:string, customInstructions?:string})=>Promise<{blockReason?:string|null}>}|null} [p.hooks]
+ * @param {ReturnType<typeof import('./lazy-instructions.mjs').createLazyInstructions>|null} [p.lazy]
+ * @param {{refreshChanged:()=>Promise<{changed:boolean, tools:any[], errors:string[]}>}|null} [p.mcp]
+ * @param {(mcpTools:any[]) => any[]} [p.composeTools]  the full tool list for a new MCP tool list
+ * @param {{drain:()=>Array<{kind:'user', message:any}|{kind:'control', subtype:string, customInstructions?:string}>}|null} [p.input]
+ * @param {(e:{trigger:string, stage:number, message:any}) => void} [p.onCompact]  a stage-2 summary was made
+ * @param {(line:string) => void} [p.log]
+ */
+export function createContextManager(p) {
+  const log = p.log ?? (() => {});
+  let cal = initialCalibration();
+  let tools = p.tools;
+  /** @type {{chars:number, images:number}|null} */
+  let lastSize = null;
+  /** @type {number|null} projection right after the last automatic compaction */
+  let lastAfter = null;
+  /** @type {Array<{trigger:string, stage:number, cleared:number, before:number, after:number, blocked?:string, error?:string}>} */
+  const compactions = [];
+
+  const active = () => (p.deferred ? p.deferred.active() : tools);
+
+  return {
+    async beforeTurn({ system, messages, signal, recordModelCall }) {
+      /** @type {{messages?:any[], append:any[], tools:any[], definitions:any[]}} */
+      const out = { append: [], tools, definitions: [] };
+
+      if (p.mcp) {
+        const r = await p.mcp.refreshChanged();
+        for (const e of r.errors) log(`MCP: ${e}`);
+        if (r.changed) {
+          tools = p.composeTools ? p.composeTools(r.tools) : tools;
+          p.deferred?.replace(tools);
+          out.tools = tools;
+          log(`MCP tool list changed; ${tools.length} tools now available`);
+        }
+      }
+
+      /** @type {{customInstructions?:string}|null} */
+      let manual = null;
+      for (const item of p.input?.drain() ?? []) {
+        if (item.kind === "control" && item.subtype === "compact") manual = item;
+        else if (item.kind === "user") out.append.push(item.message);
+      }
+
+      // Images on older tool results leave the history (each rewrite happens once, as an image ages out).
+      const pruned = pruneOldImages(messages, p.config.keepImageResults ?? DEFAULT_KEEP_IMAGE_RESULTS);
+      if (pruned.removed > 0) {
+        messages = pruned.messages;
+        out.messages = pruned.messages;
+      }
+
+      const definitions = stableToolDefinitions(active());
+      out.definitions = definitions;
+      const measure = (/** @type any[] */ history) => measureRequest({ system, messages: [...history, ...out.append], tools: definitions });
+      let size = measure(messages);
+      const projected = projectTokens(cal, size);
+      const { over, limit } = compactionLimit({ projected, contextWindow: p.config.contextWindow, threshold: p.config.threshold });
+      const minGrowth = lastAfter !== null && lastAfter >= limit ? Math.ceil(p.config.contextWindow * 0.1) : 0;
+      const auto = p.config.autoCompact && over && (lastAfter === null || projected - lastAfter >= minGrowth);
+
+      if (manual || auto) {
+        const trigger = manual ? "manual" : "auto";
+        const r = await runCompaction({
+          messages,
+          trigger,
+          config: p.config,
+          callModel: p.summarise,
+          hooks: p.hooks ?? null,
+          stillOver: (m) => compactionLimit({ projected: projectTokens(cal, measure(m)), contextWindow: p.config.contextWindow, threshold: p.config.threshold }).over,
+          instructions: p.lazy?.injected() ?? [],
+          charsPerToken: cal.charsPerToken,
+          maxTranscriptChars: charsForTokens(cal, Math.floor(p.config.contextWindow * 0.5)),
+          customInstructions: manual?.customInstructions,
+          record: recordModelCall,
+          signal,
+        });
+        if (r.stage > 0) out.messages = r.messages;
+        size = measure(r.messages);
+        const after = projectTokens(cal, size);
+        if (trigger === "auto") lastAfter = after;
+        const entry = { trigger, stage: r.stage, cleared: r.cleared, before: projected, after };
+        if (r.blocked) Object.assign(entry, { blocked: r.blocked });
+        if (r.error) Object.assign(entry, { error: r.error });
+        compactions.push(entry);
+        log(
+          `context: ${trigger} compaction, stage ${r.stage} (${r.cleared} tool result${r.cleared === 1 ? "" : "s"} cleared; ~${projected} → ~${after} tokens of ${p.config.contextWindow})` +
+            (r.blocked ? `; a PreCompact hook limited it to clearing tool results: ${r.blocked}` : "") +
+            (r.error ? `; ${r.error}` : ""),
+        );
+        if (r.stage === 2) p.onCompact?.({ trigger, stage: 2, message: r.messages[0] });
+      }
+      lastSize = size;
+      return out;
+    },
+
+    observe({ res }) {
+      if (!lastSize || !res?.ok) return;
+      const inputTokens = reportedInputTokens(res.value?.usage);
+      if (res.value?.usage?.usageSource === "estimated") return;
+      cal = calibrate(cal, { ...lastSize, inputTokens });
+    },
+
+    async afterTools({ calls, results }) {
+      if (p.deferred) {
+        const direct = calls.filter((c) => p.deferred?.isDeferred(c.name) && !p.deferred.isLoaded(c.name)).map((c) => c.name);
+        if (direct.length > 0) p.deferred.load(direct);
+      }
+      if (!p.lazy) return null;
+      const entries = [];
+      calls.forEach((c, i) => {
+        if (results[i]?.is_error) return;
+        const file = touchedPath(c.name, c.input, p.cwd);
+        if (file) entries.push(...(/** @type any */ (p.lazy).touch(file)));
+      });
+      const text = formatLazyInstructions(entries);
+      return text ? [{ type: "text", text }] : null;
+    },
+
+    /** For the result object. */
+    stats() {
+      return {
+        contextWindow: p.config.contextWindow,
+        threshold: p.config.threshold,
+        charsPerToken: Math.round(cal.charsPerToken * 100) / 100,
+        compactions: [...compactions],
+        deferredTools: p.deferred ? p.deferred.deferred().length : 0,
+        loadedTools: p.deferred ? p.deferred.loadedNames() : [],
+        instructionsLoaded: p.lazy ? p.lazy.injected().map((f) => f.path) : [],
+      };
+    },
+    /** The tools currently callable. */
+    get tools() {
+      return tools;
+    },
+  };
+}