@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/commands/index.mjs

@@ -0,0 +1,269 @@
+/**
+ * lib/engine/commands/index.mjs — slash commands in a prompt (W4-E2, conformance
+ * rows 14 and 34).
+ *
+ * A prompt (the -p prompt, or a stream-json user message) whose text starts with
+ * `/<name>` followed by whitespace or the end is a slash invocation:
+ *
+ *   /review src/loop.mjs          name "review", arguments "src/loop.mjs"
+ *   /maestro:main-session         a namespaced name
+ *   /Users/me/notes.txt           NOT an invocation (the name is not followed by
+ *                                 whitespace or the end), passed on as written
+ *
+ * The name resolves, in order, to:
+ *   1. a project command   <cwd>/.claude/commands/**\/*.md
+ *   2. a user command      ~/.claude/commands/**\/*.md
+ *   3. a skill             skills/index.mjs `findSkill` (exact name, plugin namespace
+ *                          alias, the flat installed form `<ns>-<name>`, a unique short name)
+ *   4. a plugin command    <plugin root>/commands/*.md, named `<plugin>:<name>`
+ * A command file in a subdirectory is named by its file name; `<dir>:<name>`
+ * (subdirectories joined by ":") is accepted as well. The first name wins within
+ * a source; shadowed files are reported.
+ *
+ * A command file is Markdown with optional frontmatter: `description`,
+ * `argument-hint`, `allowed-tools` (recorded, not enforced, as for skills) and
+ * `model` (the turn runs on that model's Cohort tier). Its body becomes the
+ * turn's instructions: `$ARGUMENTS` is replaced by the argument text and `$1` …
+ * `$9` by the arguments split on whitespace (quotes group); a body with neither
+ * gets the arguments appended. A skill's body is injected with its base
+ * directory, exactly as the Skill tool loads it.
+ *
+ * An unknown name is not an error: the prompt is passed on as written, with a
+ * note saying no command or skill had that name.
+ *
+ * Everything here is pure except `discoverCommands` and `expandSlashCommand`,
+ * which read through an injected fs.
+ *
+ * Authorship: the injected instruction text was written for Cohort Engine by the
+ * Cohort team, 2026-09-14.
+ *
+ * @module lib/engine/commands/index
+ */
+
+import path from "node:path";
+import { expandPluginRoots, findSkill, parseSkillFile, pluginIdentity } from "../skills/index.mjs";
+
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]*(?::[A-Za-z0-9][A-Za-z0-9_.-]*)*$/;
+const SLASH_RE = /^\/([A-Za-z0-9][A-Za-z0-9_.-]*(?::[A-Za-z0-9][A-Za-z0-9_.-]*)*)(?:[ \t\r\n]+([\s\S]*))?$/;
+const MAX_COMMAND_DEPTH = 3;
+
+/**
+ * @typedef {Object} Command
+ * @property {string} name
+ * @property {string[]} aliases
+ * @property {string} description
+ * @property {string|null} argumentHint
+ * @property {string[]} allowedTools
+ * @property {string|null} model
+ * @property {string} file
+ * @property {'project'|'user'|'plugin'} source
+ */
+
+/** @param {unknown} v */
+function toolList(v) {
+  if (Array.isArray(v)) return v.map(String).map((s) => s.trim()).filter(Boolean);
+  if (typeof v === "string") return v.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+/**
+ * Is this text a slash invocation? Pure.
+ * @param {string} text
+ * @returns {{name:string, args:string}|null}
+ */
+export function parseSlashCommand(text) {
+  const m = SLASH_RE.exec(String(text ?? "").replace(/^\s+/, "").replace(/\s+$/, ""));
+  return m ? { name: m[1], args: (m[2] ?? "").trim() } : null;
+}
+
+/**
+ * Split arguments on whitespace; single or double quotes group. Pure.
+ * @param {string} args
+ */
+export function splitArguments(args) {
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  for (let m = re.exec(args); m; m = re.exec(args)) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}
+
+/**
+ * A command body with its arguments substituted. Pure.
+ * @param {string} body @param {string} args
+ */
+export function substituteArguments(body, args) {
+  const positional = splitArguments(args);
+  const hasArguments = body.includes("$ARGUMENTS");
+  const hasPositional = /\$[1-9](?!\d)/.test(body);
+  let out = hasArguments ? body.split("$ARGUMENTS").join(args) : body;
+  if (hasPositional) out = out.replace(/\$([1-9])(?!\d)/g, (_, n) => positional[Number(n) - 1] ?? "");
+  if (!hasArguments && !hasPositional && args) out = `${out}\n\nArguments: ${args}`;
+  return out;
+}
+
+/**
+ * @param {{file:string, text:string, name:string, aliases:string[], source:Command['source']}} p
+ * @returns {Command}
+ */
+export function commandFromFile({ file, text, name, aliases, source }) {
+  const { frontmatter: fm, body } = parseSkillFile(text);
+  let description = typeof fm.description === "string" ? fm.description.trim() : "";
+  if (description === "") description = (body.split(/\r?\n/).map((l) => l.replace(/^#+\s*/, "").trim()).find((l) => l !== "") ?? "").slice(0, 200);
+  const hint = fm["argument-hint"] ?? fm.argument_hint;
+  const model = typeof fm.model === "string" && fm.model.trim() !== "" ? fm.model.trim() : null;
+  return { name, aliases, description, argumentHint: typeof hint === "string" ? hint : null, allowedTools: toolList(fm["allowed-tools"] ?? fm.allowed_tools), model, file, source };
+}
+
+/**
+ * @typedef {Object} CommandFs
+ * @property {(p:string)=>string} readFile
+ * @property {(p:string)=>string[]} readdir
+ * @property {(p:string)=>boolean} isFile
+ * @property {(p:string)=>boolean} isDir
+ */
+
+/**
+ * @param {object} p
+ * @param {string|null} p.userDir        ~/.claude (null: no user commands)
+ * @param {string|null} p.cwd            null: no project commands (--bare)
+ * @param {Array<{dir:string}>} [p.pluginDirs]
+ * @param {CommandFs} p.fs
+ * @returns {{commands: Command[], errors: string[]}}
+ */
+export function discoverCommands({ userDir, cwd, pluginDirs = [], fs }) {
+  /** @type {Command[]} */
+  const commands = [];
+  const errors = [];
+  const names = (/** @type string */ dir) => {
+    try {
+      return fs.readdir(dir).sort();
+    } catch {
+      return [];
+    }
+  };
+  /** @param {string} dir @param {Command['source']} source @param {string|null} namespace @param {string[]} nsAliases */
+  const scan = (dir, source, namespace, nsAliases) => {
+    /** @type {Map<string, Command>} */
+    const seen = new Map();
+    /** @param {string} d @param {string[]} parents */
+    const walk = (d, parents) => {
+      if (!fs.isDir(d)) return;
+      for (const entry of names(d)) {
+        const full = path.join(d, entry);
+        if (entry.startsWith(".")) continue;
+        if (fs.isDir(full)) {
+          if (namespace === null && parents.length + 1 < MAX_COMMAND_DEPTH) walk(full, [...parents, entry]);
+          continue;
+        }
+        if (!entry.endsWith(".md") || !fs.isFile(full)) continue;
+        const base = entry.slice(0, -3);
+        if (!NAME_RE.test(base)) continue;
+        const name = namespace ? `${namespace}:${base}` : base;
+        const aliases = namespace ? nsAliases.map((a) => `${a}:${base}`) : parents.length ? [[...parents, base].join(":")] : [];
+        if (seen.has(name)) {
+          errors.push(`command "${name}" at ${full} is shadowed by ${seen.get(name)?.file}`);
+          continue;
+        }
+        let text;
+        try {
+          text = fs.readFile(full);
+        } catch (e) {
+          errors.push(`command ${full}: cannot read (${e instanceof Error ? e.message : e})`);
+          continue;
+        }
+        const c = commandFromFile({ file: full, text, name, aliases: aliases.filter((a) => NAME_RE.test(a)), source });
+        seen.set(name, c);
+        commands.push(c);
+      }
+    };
+    walk(dir, []);
+  };
+  if (cwd) scan(path.join(cwd, ".claude", "commands"), "project", null, []);
+  if (userDir) scan(path.join(userDir, "commands"), "user", null, []);
+  for (const root of expandPluginRoots(pluginDirs, fs)) {
+    if (!fs.isDir(root)) continue; // skills discovery reports a missing plugin root
+    const identity = pluginIdentity(root, fs);
+    scan(path.join(root, "commands"), "plugin", identity.name, identity.aliases);
+  }
+  return { commands, errors };
+}
+
+/**
+ * Find a command by name among one source's commands. Pure.
+ * @param {Command[]} commands @param {string} name
+ */
+function findCommand(commands, name) {
+  const exact = commands.find((c) => c.name === name) ?? commands.find((c) => c.aliases.includes(name));
+  if (exact) return exact;
+  const colon = name.indexOf(":");
+  if (colon > 0 && name.indexOf(":", colon + 1) === -1) return commands.find((c) => c.name === `${name.slice(0, colon)}-${name.slice(colon + 1)}`) ?? null;
+  return null;
+}
+
+/**
+ * What a prompt's slash invocation names. Pure.
+ * @param {{text:string, commands:Command[], skills:import('../skills/index.mjs').Skill[]}} p
+ * @returns {{kind:'none'} | {kind:'command', name:string, args:string, command:Command} | {kind:'skill', name:string, args:string, skill:import('../skills/index.mjs').Skill} | {kind:'unknown', name:string, args:string, reason:string|null}}
+ */
+export function resolveSlashCommand({ text, commands, skills }) {
+  const parsed = parseSlashCommand(text);
+  if (!parsed) return { kind: "none" };
+  const { name, args } = parsed;
+  for (const source of /** @type {const} */ (["project", "user"])) {
+    const c = findCommand(commands.filter((x) => x.source === source), name);
+    if (c) return { kind: "command", name, args, command: c };
+  }
+  const s = findSkill(skills, name);
+  if (s.ok) return { kind: "skill", name, args, skill: s.skill };
+  const p = findCommand(commands.filter((x) => x.source === "plugin"), name);
+  if (p) return { kind: "command", name, args, command: p };
+  // A short name that several plugin skills share is ambiguous, not unknown.
+  return { kind: "unknown", name, args, reason: /matches several skills/.test(s.error) ? s.error : null };
+}
+
+/**
+ * The note an unknown slash command's prompt carries. Pure.
+ * @param {string} name @param {string|null} [reason]
+ */
+export function unknownCommandNote(name, reason = null) {
+  return `[Note: "/${name}" is not a command or skill available in this session${reason ? ` (${reason})` : ""}; the message above is passed on as written.]`;
+}
+
+/**
+ * The text a resolved invocation puts in the turn, read through `fs`.
+ * @param {Exclude<ReturnType<typeof resolveSlashCommand>, {kind:'none'}>} resolved
+ * @param {{readFile:(p:string)=>string}} fs
+ * @param {string} original  the prompt as typed
+ * @returns {{ok:true, text:string, model:string|null, allowedTools:string[], invoked:{kind:string, name:string, file:string|null}|null} | {ok:false, error:string}}
+ */
+export function expandSlashCommand(resolved, fs, original) {
+  if (resolved.kind === "unknown") {
+    return { ok: true, text: `${original}\n\n${unknownCommandNote(resolved.name, resolved.reason)}`, model: null, allowedTools: [], invoked: null };
+  }
+  const file = resolved.kind === "command" ? resolved.command.file : resolved.skill.file;
+  let raw;
+  try {
+    raw = fs.readFile(file);
+  } catch (e) {
+    return { ok: false, error: `/${resolved.name}: ${file} could not be read (${e instanceof Error ? e.message : e})` };
+  }
+  const body = substituteArguments(parseSkillFile(raw).body.trim(), resolved.args);
+  if (resolved.kind === "command") {
+    const c = resolved.command;
+    return {
+      ok: true,
+      text: `The user ran the /${c.name} command${resolved.args ? ` with the arguments: ${resolved.args}` : ""}. Carry out its instructions, which follow.\n\n${body}`,
+      model: c.model,
+      allowedTools: c.allowedTools,
+      invoked: { kind: "command", name: c.name, file: c.file },
+    };
+  }
+  const s = resolved.skill;
+  return {
+    ok: true,
+    text: `The user invoked the "${s.name}" skill${resolved.args ? ` with the arguments: ${resolved.args}` : ""}. Its base directory is ${s.baseDir}; resolve relative paths in these instructions against it. Follow its instructions below.\n\n${body}`,
+    model: null,
+    allowedTools: s.allowedTools,
+    invoked: { kind: "skill", name: s.name, file: s.file },
+  };
+}

package/lib/engine/context/budget.mjs

@@ -0,0 +1,219 @@
+/**
+ * lib/engine/context/budget.mjs — how big a request is, and when to compact (pure).
+ *
+ * Context windows are DATA: `CONTEXT_WINDOWS` maps each Cohort tier to the
+ * window the engine plans against. A settings file (`cohort.contextWindows`)
+ * or `COHORT_ENGINE_CONTEXT_WINDOW` overrides it, because the slot map behind a
+ * tier is decided by the parity eval and can change without an engine release.
+ *
+ * Estimation is a characters-per-token heuristic, CALIBRATED by the provider:
+ * after every model call the loop reports the input tokens the gateway counted
+ * for a request of a known size (`calibrate`). The projection for the next
+ * request is then the provider's own count plus the growth since, converted at
+ * the observed ratio (`projectTokens`). Before the first call the default
+ * ratio (4 characters per token) is used. Images are counted at a flat
+ * estimate each; their bytes say little about their token cost.
+ *
+ * Compaction fires when the projected input reaches `threshold` of the window
+ * (default 85%). Everything here is a function of its inputs: no clock, no
+ * environment read — `resolveContextConfig` takes the environment as a
+ * parameter.
+ *
+ * @module lib/engine/context/budget
+ */
+
+/** The window, in tokens, the engine plans against per tier. */
+export const CONTEXT_WINDOWS = Object.freeze({
+  "cohort-agentic": 1_000_000,
+  "cohort-reason": 1_000_000,
+  "cohort-fast": 128_000,
+  "cohort-extract": 128_000,
+  "cohort-vision": 128_000,
+});
+/** A tier the table does not know gets the smallest window any tier has. */
+export const DEFAULT_CONTEXT_WINDOW = 128_000;
+export const DEFAULT_COMPACT_THRESHOLD = 0.85;
+export const DEFAULT_CHARS_PER_TOKEN = 4;
+/** Tool results kept verbatim by stage-1 compaction. */
+export const DEFAULT_KEEP_TOOL_RESULTS = 6;
+/** Messages kept verbatim after a stage-2 summary (rounded back to an assistant turn). */
+export const DEFAULT_KEEP_RECENT_MESSAGES = 6;
+/** Image-carrying tool results whose images stay in the history (images.mjs). */
+export const DEFAULT_KEEP_IMAGE_RESULTS = 3;
+/** Tokens one image is assumed to cost. */
+export const IMAGE_TOKEN_ESTIMATE = 1_600;
+const MIN_RATIO = 1;
+const MAX_RATIO = 10;
+
+/**
+ * @typedef {Object} ContextConfig
+ * @property {number} contextWindow
+ * @property {number} threshold          0 < threshold ≤ 1
+ * @property {boolean} autoCompact
+ * @property {number} keepToolResults
+ * @property {number} keepRecentMessages
+ * @property {number} [keepImageResults]  image-carrying tool results whose images stay in the history
+ */
+
+/**
+ * @param {string} tier
+ * @param {Record<string, unknown>} [overrides]  settings `cohort.contextWindows`
+ */
+export function contextWindowFor(tier, overrides = {}) {
+  const o = overrides?.[tier];
+  if (typeof o === "number" && Number.isInteger(o) && o > 0) return o;
+  return /** @type {Record<string,number>} */ (CONTEXT_WINDOWS)[tier] ?? DEFAULT_CONTEXT_WINDOW;
+}
+
+/**
+ * Parse a threshold: a fraction (0.85) or a percentage (85).
+ * @param {unknown} v @returns {number|null}
+ */
+export function parseThreshold(v) {
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v.trim().replace(/%$/, "")) : NaN;
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const f = n > 1 ? n / 100 : n;
+  return f > 0 && f <= 1 ? f : null;
+}
+
+/**
+ * The run's context settings. Precedence: environment > settings > defaults.
+ *
+ *   settings  cohort.contextWindows {tier: tokens}
+ *             cohort.compaction {threshold, auto, keepToolResults, keepRecentMessages, keepImageResults}
+ *   env       COHORT_ENGINE_CONTEXT_WINDOW, COHORT_ENGINE_COMPACT_THRESHOLD,
+ *             COHORT_ENGINE_AUTO_COMPACT (0/false/off disables automatic compaction)
+ *
+ * @param {{tier:string, settings?:any, env?:Record<string,string|undefined>}} p
+ * @returns {{config: ContextConfig, warnings: string[]}}
+ */
+export function resolveContextConfig({ tier, settings = {}, env = {} }) {
+  const warnings = [];
+  const s = settings && typeof settings === "object" ? settings : {};
+  const comp = s.compaction && typeof s.compaction === "object" ? s.compaction : {};
+  let contextWindow = contextWindowFor(tier, s.contextWindows);
+  if (env.COHORT_ENGINE_CONTEXT_WINDOW !== undefined && env.COHORT_ENGINE_CONTEXT_WINDOW !== "") {
+    const n = Number(env.COHORT_ENGINE_CONTEXT_WINDOW);
+    if (Number.isInteger(n) && n > 0) contextWindow = n;
+    else warnings.push(`COHORT_ENGINE_CONTEXT_WINDOW "${env.COHORT_ENGINE_CONTEXT_WINDOW}" is not a positive integer (ignored)`);
+  }
+  let threshold = DEFAULT_COMPACT_THRESHOLD;
+  if (comp.threshold !== undefined) {
+    const t = parseThreshold(comp.threshold);
+    if (t === null) warnings.push(`settings cohort.compaction.threshold ${JSON.stringify(comp.threshold)} is not a fraction or percentage (ignored)`);
+    else threshold = t;
+  }
+  if (env.COHORT_ENGINE_COMPACT_THRESHOLD !== undefined && env.COHORT_ENGINE_COMPACT_THRESHOLD !== "") {
+    const t = parseThreshold(env.COHORT_ENGINE_COMPACT_THRESHOLD);
+    if (t === null) warnings.push(`COHORT_ENGINE_COMPACT_THRESHOLD "${env.COHORT_ENGINE_COMPACT_THRESHOLD}" is not a fraction or percentage (ignored)`);
+    else threshold = t;
+  }
+  let autoCompact = comp.auto !== false;
+  const envAuto = String(env.COHORT_ENGINE_AUTO_COMPACT ?? "").trim().toLowerCase();
+  if (["0", "false", "off", "no"].includes(envAuto)) autoCompact = false;
+  else if (["1", "true", "on", "yes"].includes(envAuto)) autoCompact = true;
+  const posInt = (/** @type unknown */ v, /** @type number */ d) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : d);
+  return {
+    config: {
+      contextWindow,
+      threshold,
+      autoCompact,
+      keepToolResults: posInt(comp.keepToolResults, DEFAULT_KEEP_TOOL_RESULTS),
+      keepRecentMessages: Math.max(2, posInt(comp.keepRecentMessages, DEFAULT_KEEP_RECENT_MESSAGES)),
+      keepImageResults: posInt(comp.keepImageResults, DEFAULT_KEEP_IMAGE_RESULTS),
+    },
+    warnings,
+  };
+}
+
+/**
+ * The size of one request, in characters and images.
+ * @param {{system?:string, messages?:any[], tools?:any[]}} req
+ * @returns {{chars:number, images:number}}
+ */
+export function measureRequest({ system = "", messages = [], tools = [] }) {
+  let chars = String(system ?? "").length;
+  let images = 0;
+  if (tools.length > 0) chars += JSON.stringify(tools).length;
+  for (const m of messages) {
+    if (!m || !Array.isArray(m.content)) continue;
+    for (const b of m.content) {
+      if (!b || typeof b !== "object") continue;
+      switch (b.type) {
+        case "text":
+          chars += String(b.text ?? "").length;
+          break;
+        case "tool_use":
+          chars += String(b.name ?? "").length + (b.rawInput ? String(b.rawInput).length : JSON.stringify(b.input ?? {}).length);
+          break;
+        case "tool_result":
+          chars += String(b.content ?? "").length;
+          if (Array.isArray(b.images)) images += b.images.length;
+          break;
+        case "thinking":
+          chars += String(b.thinking ?? "").length;
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  return { chars, images };
+}
+
+/**
+ * @typedef {{charsPerToken:number, anchorChars:number|null, anchorImages:number, anchorTokens:number|null}} Calibration
+ */
+
+/** @returns {Calibration} */
+export function initialCalibration(charsPerToken = DEFAULT_CHARS_PER_TOKEN) {
+  return { charsPerToken, anchorChars: null, anchorImages: 0, anchorTokens: null };
+}
+
+/**
+ * Input tokens a normalised usage record says the provider counted.
+ * @param {import('../wire/usage.mjs').NormalisedUsage|null|undefined} u
+ */
+export function reportedInputTokens(u) {
+  if (!u) return 0;
+  return (u.inputUncached || 0) + (u.cacheRead || 0) + (u.cacheWrite5m || 0) + (u.cacheWrite1h || 0);
+}
+
+/**
+ * Fold one provider measurement into the calibration. A request with no
+ * reported input (usage missing or estimated) leaves it unchanged.
+ * @param {Calibration} cal
+ * @param {{chars:number, images:number, inputTokens:number}} observed
+ * @returns {Calibration}
+ */
+export function calibrate(cal, { chars, images, inputTokens }) {
+  if (!(inputTokens > 0) || !(chars > 0)) return cal;
+  const textTokens = inputTokens - images * IMAGE_TOKEN_ESTIMATE;
+  const ratio = textTokens > 0 ? Math.min(MAX_RATIO, Math.max(MIN_RATIO, chars / textTokens)) : cal.charsPerToken;
+  return { charsPerToken: ratio, anchorChars: chars, anchorImages: images, anchorTokens: inputTokens };
+}
+
+/**
+ * Projected input tokens for a request of this size.
+ * @param {Calibration} cal @param {{chars:number, images:number}} size
+ */
+export function projectTokens(cal, { chars, images }) {
+  if (cal.anchorTokens !== null && cal.anchorChars !== null && chars >= cal.anchorChars) {
+    return cal.anchorTokens + Math.ceil((chars - cal.anchorChars) / cal.charsPerToken) + Math.max(0, images - cal.anchorImages) * IMAGE_TOKEN_ESTIMATE;
+  }
+  return Math.ceil(chars / cal.charsPerToken) + images * IMAGE_TOKEN_ESTIMATE;
+}
+
+/** Characters that fit in `tokens` at the calibrated ratio. @param {Calibration} cal @param {number} tokens */
+export function charsForTokens(cal, tokens) {
+  return Math.floor(tokens * cal.charsPerToken);
+}
+
+/**
+ * @param {{projected:number, contextWindow:number, threshold:number}} p
+ * @returns {{over:boolean, limit:number}}
+ */
+export function compactionLimit({ projected, contextWindow, threshold }) {
+  const limit = Math.floor(contextWindow * threshold);
+  return { over: projected >= limit, limit };
+}

package/lib/engine/context/cache.mjs

@@ -0,0 +1,125 @@
+/**
+ * lib/engine/context/cache.mjs — prompt-cache discipline (pure).
+ *
+ * A supplier caches a request's PREFIX. Every cached token is read at a
+ * fraction of the input price, so what the engine controls is that the prefix
+ * of turn N+1 is byte-identical to the whole of turn N, and that two runs of
+ * the same seat in the same project start from the same bytes:
+ *
+ *   · the system prompt is built once per run; per-run values (date,
+ *     working directory) sit at its end, and nothing is added to it mid-run —
+ *     hook context, reminders, lazily found instruction files and compaction
+ *     summaries are appended as later MESSAGES;
+ *   · tool definitions are ordered deterministically: built-ins in registry
+ *     order, then engine tools, then MCP tools sorted by name, and every
+ *     definition is serialised with its keys sorted (`stableToolDefinitions`),
+ *     so a server that lists its tools or schema keys in a different order on
+ *     the next run does not change the bytes;
+ *   · the tool list only ever GROWS at its tail (deferred tools loaded by
+ *     ToolSearch are appended in load order), so a load rewrites the cache from
+ *     the tool list on once, after which the new prefix is stable again.
+ *
+ * Anthropic breakpoints (`planAnthropicBreakpoints`, at most four): the tail
+ * of the tool list, the last system block, the last user message of the
+ * PREVIOUS turn (it read or wrote the cache last time, so this turn reads it
+ * even when many new blocks follow it), and the last block of the final
+ * message (which writes the prefix the next turn will read). Placement is a
+ * function of the history's shape only. After compaction the history is
+ * shorter, and the same function places the two message breakpoints on the new
+ * history — the tool and system breakpoints, and their bytes, are unchanged.
+ *
+ * OpenAI wire: the supplier caches automatically by prefix. `promptCacheKey`
+ * derives the routing key (`prompt_cache_key`) sent when the gateway
+ * advertises support: one key per project and tier, so sessions of one seat
+ * on one project share cache routing.
+ *
+ * @module lib/engine/context/cache
+ */
+
+import { createHash } from "node:crypto";
+
+export const MAX_CACHE_BREAKPOINTS = 4;
+
+/**
+ * @param {{toolCount:number, hasSystem:boolean, messages:Array<{role:string, content:any[]}>}} shape
+ * @returns {{tool:number|null, system:boolean, messages:number[]}}  message indices, ascending
+ */
+export function planAnthropicBreakpoints({ toolCount, hasSystem, messages }) {
+  const tool = toolCount > 0 ? toolCount - 1 : null;
+  const picks = new Set();
+  const last = messages.length - 1;
+  if (last >= 0) {
+    picks.add(last);
+    // The previous turn's final message: the last user message that precedes
+    // the last assistant message.
+    let a = last;
+    while (a >= 0 && messages[a].role !== "assistant") a--;
+    for (let i = a - 1; i >= 0; i--) {
+      if (messages[i].role === "user") {
+        picks.add(i);
+        break;
+      }
+    }
+  }
+  const budget = MAX_CACHE_BREAKPOINTS - (tool !== null ? 1 : 0) - (hasSystem ? 1 : 0);
+  const chosen = [...picks].sort((x, y) => y - x).slice(0, Math.max(0, budget)).sort((x, y) => x - y);
+  return { tool, system: hasSystem, messages: chosen };
+}
+
+/**
+ * The index of the block in a message that may carry `cache_control`: the last
+ * block that is not a thinking block (thinking blocks cannot be marked).
+ * @param {{content:any[]}} message @returns {number}
+ */
+export function markableBlockIndex(message) {
+  for (let i = message.content.length - 1; i >= 0; i--) if (message.content[i]?.type !== "thinking") return i;
+  return -1;
+}
+
+/**
+ * A deep copy with object keys sorted, so equal values serialise to equal bytes.
+ * @param {unknown} v @returns {any}
+ */
+export function canonicalJson(v) {
+  if (Array.isArray(v)) return v.map(canonicalJson);
+  if (!v || typeof v !== "object") return v;
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const k of Object.keys(v).sort()) out[k] = canonicalJson(/** @type any */ (v)[k]);
+  return out;
+}
+
+/**
+ * Deterministic order: non-MCP tools as given, then MCP tools sorted by name.
+ * @template {{name:string, mcp?:unknown}} T
+ * @param {T[]} tools @returns {T[]}
+ */
+export function stableToolOrder(tools) {
+  const plain = tools.filter((t) => !t.mcp);
+  const mcp = tools.filter((t) => t.mcp).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return [...plain, ...mcp];
+}
+
+/**
+ * Wire-facing definitions with canonical schemas.
+ * @param {Array<{name:string, description:string, input_schema:object}>} tools
+ */
+export function stableToolDefinitions(tools) {
+  return tools.map((t) => ({ name: t.name, description: t.description, input_schema: canonicalJson(t.input_schema) }));
+}
+
+/**
+ * The OpenAI-wire prompt-cache routing key for a project and tier.
+ * @param {{cwd:string, model:string}} p
+ */
+export function promptCacheKey({ cwd, model }) {
+  return `cohort-${createHash("sha256").update(`${cwd}\u0000${model}`).digest("hex").slice(0, 32)}`;
+}
+
+/**
+ * Count `cache_control` markers anywhere in a request body (a test and audit aid).
+ * @param {unknown} body
+ */
+export function countCacheBreakpoints(body) {
+  return (JSON.stringify(body).match(/"cache_control"/g) || []).length;
+}