nubos-pilot 1.3.0 → 1.3.1

package/bin/np-tools/_commands.cjs

@@ -89,6 +89,8 @@ const COMMANDS = [
   { name: 'knowledge-index',         category: 'Utility', description: 'Build BM25-light index over .nubos-pilot/**/*.md → .nubos-pilot/state/knowledge-index.json', description_de: 'Baut BM25-Light-Index über .nubos-pilot/**/*.md → .nubos-pilot/state/knowledge-index.json' },
   { name: 'knowledge-search',        category: 'Utility', description: 'Query the knowledge index; returns top-N JSON hits (rel_path + lines + score + preview). Pass --task <id> inside a Nubosloop task to record Rule 9 audit evidence', description_de: 'Sucht im Knowledge-Index; liefert Top-N-JSON-Treffer (rel_path + Zeilen + Score + Preview). --task <id> innerhalb eines Nubosloop-Tasks schreibt den Rule-9-Audit-Nachweis' },
   { name: 'knowledge-stats',         category: 'Utility', description: 'Print knowledge-index size + grouping (auto-builds if missing)', description_de: 'Gibt Knowledge-Index-Größe + Gruppierung aus (baut auto bei Fehlen)' },
+  { name: 'elision-get',             category: 'Utility', description: 'Retrieve the original text behind a ⟦elided:<hash>⟧ compression marker. Reversible context compression (ADR-Elision). Positional <hash> or --hash; --json for envelope', description_de: 'Holt den Originaltext hinter einem ⟦elided:<hash>⟧ Kompressions-Marker. Reversible Kontext-Kompression (ADR-Elision). Positional <hash> oder --hash; --json für Envelope' },
+  { name: 'elision-bench',           category: 'Utility', description: 'Measure elision compression: deterministic fidelity (ratio + critical-line preservation + byte-exact reversibility) over a fixture corpus; --with-model adds answer-equivalence (raw vs compressed). --size <small|medium|large> runs a scaled corpus with a deterministic --holdout control group (--max-cases N) and an estimated token saving (--price-per-mtok <p> [--currency EUR] adds a cost estimate). --json, --tier <name>', description_de: 'Misst die Elision-Kompression: deterministische Fidelity (Ratio + Erhalt kritischer Zeilen + byte-exakte Reversibilität) über ein Fixture-Korpus; --with-model ergänzt Antwort-Äquivalenz (roh vs. komprimiert). --size <small|medium|large> fährt ein skaliertes Korpus mit deterministischer --holdout-Kontrollgruppe (--max-cases N) und geschätzter Token-Ersparnis (--price-per-mtok <p> [--currency EUR] ergänzt eine Kostenschätzung). --json, --tier <name>' },
   { name: 'context-stats',           category: 'Utility', description: 'Aggregated context-budget stats (file counts + bytes per group, knowledge-index size)', description_de: 'Aggregierte Context-Budget-Stats (Dateien/Bytes pro Gruppe, Knowledge-Index-Größe)' },
   { name: 'session-snapshot-write',  category: 'Utility', description: 'Capture session snapshot (current_task + recent commits + open handoffs) for resume', description_de: 'Erfasst Session-Snapshot (current_task + letzte Commits + offene Handoffs) für Resume' },
   { name: 'session-snapshot-read',   category: 'Utility', description: 'Print last session snapshot as JSON', description_de: 'Gibt letzten Session-Snapshot als JSON aus' },

package/bin/np-tools/_elision-proxy-entry.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+const proxy = require('../../lib/elision-proxy.cjs');
+
+proxy.start({
+  cwd: process.env.ELISION_PROXY_CWD || process.cwd(),
+  upstream: process.env.ELISION_PROXY_UPSTREAM || undefined,
+}).then(({ baseUrl }) => {
+  if (process.send) process.send({ ready: true, baseUrl });
+}).catch((err) => {
+  if (process.send) process.send({ ready: false, error: String(err && err.message) });
+  process.exit(1);
+});

package/bin/np-tools/elision-bench.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+const bench = require('../../lib/elision-bench.cjs');
+
+function _parseArgs(args) {
+  const out = { json: false, withModel: false, tier: 'frontier', size: null, holdout: 0.2, maxCases: null, charsPerToken: null, pricePerMTok: null, currency: null };
+  for (let i = 0; i < (args || []).length; i += 1) {
+    const a = args[i];
+    if (a === '--json') { out.json = true; continue; }
+    if (a === '--with-model') { out.withModel = true; continue; }
+    if (a === '--tier') { out.tier = args[++i] || out.tier; continue; }
+    if (a === '--size') { out.size = args[++i] || out.size; continue; }
+    if (a === '--holdout') { const v = parseFloat(args[++i]); if (Number.isFinite(v)) out.holdout = v; continue; }
+    if (a === '--max-cases') { const v = parseInt(args[++i], 10); if (Number.isFinite(v)) out.maxCases = v; continue; }
+    if (a === '--chars-per-token') { const v = parseFloat(args[++i]); if (Number.isFinite(v)) out.charsPerToken = v; continue; }
+    if (a === '--price-per-mtok') { const v = parseFloat(args[++i]); if (Number.isFinite(v)) out.pricePerMTok = v; continue; }
+    if (a === '--currency') { out.currency = args[++i] || out.currency; continue; }
+  }
+  return out;
+}
+
+async function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+
+  if (parsed.size) {
+    const scale = bench.runScale({ cwd, size: parsed.size, holdoutRatio: parsed.holdout, maxCases: parsed.maxCases, charsPerToken: parsed.charsPerToken, pricePerMTok: parsed.pricePerMTok, currency: parsed.currency });
+    stdout.write((parsed.json ? JSON.stringify({ scale }) : bench.formatScale(scale)) + '\n');
+    return scale.summary.invariants_ok ? 0 : 1;
+  }
+
+  const fidelity = bench.runFidelity({ cwd });
+  let equivalence = null;
+
+  if (parsed.withModel) {
+    const { resolveFromConfig } = require('./resolve-model.cjs');
+    const { chat } = require('../../lib/runtime/providers/openai-compat.cjs');
+    const res = resolveFromConfig({ agentOrTier: parsed.tier, cwd, format: 'json' });
+    if (!res || !res.model || !res.baseUrl) {
+      stdout.write((parsed.json ? JSON.stringify({ fidelity, equivalence: null, error: 'no-provider' }) : 'No off-host provider resolved for tier "' + parsed.tier + '" — equivalence skipped.') + '\n');
+      return fidelity.summary.invariants_ok ? 0 : 1;
+    }
+    const provider = { baseUrl: res.baseUrl, apiKeyEnv: res.apiKeyEnv, model: res.model };
+    equivalence = await bench.runEquivalence({ chatImpl: chat, provider });
+  }
+
+  if (parsed.json) {
+    stdout.write(JSON.stringify({ fidelity, equivalence }) + '\n');
+  } else {
+    stdout.write(bench.formatReport(fidelity) + '\n');
+    if (equivalence) {
+      stdout.write('\nAnswer equivalence — ' + equivalence.summary.equivalent + '/' + equivalence.summary.cases
+        + ' equivalent, regressions: ' + (equivalence.summary.regressions.length ? equivalence.summary.regressions.join(', ') : 'none') + '\n');
+      for (const c of equivalence.cases) {
+        stdout.write('  ' + (c.regression ? '✗' : '✓') + ' ' + c.name + ' (raw '
+          + (c.raw_ok ? 'ok' : 'miss') + ', compressed ' + (c.compressed_ok ? 'ok' : 'miss') + ')\n');
+      }
+    }
+  }
+
+  const ok = fidelity.summary.invariants_ok && (!equivalence || equivalence.summary.no_regression);
+  return ok ? 0 : 1;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/elision-get.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const elision = require('../../lib/elision.cjs');
+
+function _parseArgs(args) {
+  const out = { hash: null, json: false };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--hash') { out.hash = args[++i] || null; continue; }
+    if (a === '--json') { out.json = true; continue; }
+    positional.push(a);
+  }
+  if (out.hash == null) out.hash = positional.join('').trim() || null;
+  return out;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+  if (!parsed.hash) {
+    throw new NubosPilotError(
+      'elision-get-missing-hash',
+      'elision-get requires a hash (positional or --hash)',
+      { hint: 'hash is the 12-char id from a ⟦elided:…⟧ marker' },
+    );
+  }
+  const result = elision.retrieve(parsed.hash, cwd);
+  if (parsed.json) {
+    stdout.write(JSON.stringify(result));
+    return result.status === 'ok' ? 0 : 1;
+  }
+  if (result.status === 'ok') {
+    stdout.write(result.original);
+    return 0;
+  }
+  if (result.status === 'expired') {
+    stdout.write('[elision ' + parsed.hash + ' expired — original no longer cached (ttl elapsed)]\n');
+    return 1;
+  }
+  stdout.write('[elision ' + parsed.hash + ' not found]\n');
+  return 1;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/elision-get.test.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const elisionGet = require('./elision-get.cjs');
+const elision = require('../../lib/elision.cjs');
+const { NubosPilotError } = require('../../lib/core.cjs');
+
+function sandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-elisionget-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  return root;
+}
+
+function capture() {
+  const chunks = [];
+  return { stream: { write: (s) => chunks.push(s) }, text: () => chunks.join('') };
+}
+
+test('ELISIONGET-1: prints the original for a known hash', () => {
+  const root = sandbox();
+  try {
+    const hash = elision.store('the original payload', { type: 'plain' }, root);
+    const out = capture();
+    const code = elisionGet.run([hash], { cwd: root, stdout: out.stream });
+    assert.equal(code, 0);
+    assert.equal(out.text(), 'the original payload');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('ELISIONGET-2: unknown hash exits 1 with a not-found notice', () => {
+  const root = sandbox();
+  try {
+    const out = capture();
+    const code = elisionGet.run(['aaaaaaaaaaaa'], { cwd: root, stdout: out.stream });
+    assert.equal(code, 1);
+    assert.match(out.text(), /not found/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('ELISIONGET-3: --json emits the retrieval envelope', () => {
+  const root = sandbox();
+  try {
+    const hash = elision.store('payload', { type: 'plain' }, root);
+    const out = capture();
+    const code = elisionGet.run([hash, '--json'], { cwd: root, stdout: out.stream });
+    assert.equal(code, 0);
+    const env = JSON.parse(out.text());
+    assert.equal(env.status, 'ok');
+    assert.equal(env.original, 'payload');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('ELISIONGET-4: missing hash throws', () => {
+  assert.throws(() => elisionGet.run([], { cwd: process.cwd(), stdout: { write() {} } }), NubosPilotError);
+});

package/bin/np-tools/loop-run-round.cjs

@@ -6,16 +6,37 @@ const path = require('node:path');
 const { NubosPilotError, safeAssign } = require('../../lib/core.cjs');
 const safePath = require('../../lib/safe-path.cjs');
 
-function _resolveInsideCwdOrTmp(p, cwd, label, errorCode) {
-  return safePath.assertInsideCwdOrTmp(p, cwd, label, errorCode);
-}
 const checkpoint = require('../../lib/checkpoint.cjs');
 const nubosloop = require('../../lib/nubosloop.cjs');
 const messaging = require('../../lib/messaging.cjs');
+const compress = require('../../lib/compress.cjs');
+const elision = require('../../lib/elision.cjs');
+const logger = require('../../lib/logger.cjs').child('loop-run-round');
 const args = require('./_args.cjs');
 
 const { TASK_ID_RE } = require('../../lib/ids.cjs');
 
+function _resolveInsideCwdOrTmp(p, cwd, label, errorCode) {
+  return safePath.assertInsideCwdOrTmp(p, cwd, label, errorCode);
+}
+
+function _verifyExcerpt(verifyOutput, cwd) {
+  const s = String(verifyOutput);
+  const cx = elision.compressionContext(cwd);
+  const maxBytes = cx.verifyMaxBytes;
+  if (s.length <= maxBytes) return s;
+  if (cx.enabled) {
+    try {
+      const crushed = compress.crushLogToBudget(s, maxBytes);
+      if (crushed && crushed.length < s.length) {
+        const hash = cx.store ? cx.store(s, 'log') : null;
+        return crushed + (hash ? '\n' + compress.marker(hash, 'full verify log') : '');
+      }
+    } catch (err) { logger.warn('verify compression skipped', { cause: err && err.message }); }
+  }
+  return '…[truncated head, original ' + s.length + ' bytes — see VERIFY_LOG]\n' + s.slice(-maxBytes);
+}
+
 const VALID_PHASES = new Set([
   'preflight',
   'post-researcher',
@@ -182,16 +203,9 @@ function _runPostExecutor(taskId, list, cwd) {
     }
   }
   const green = code === 0;
-  const VERIFY_TAIL_BYTES = 2000;
   let verifyExcerpt = null;
   if (verifyOutput) {
-    const s = String(verifyOutput);
-    if (s.length > VERIFY_TAIL_BYTES) {
-      verifyExcerpt = '…[truncated head, original ' + s.length + ' bytes — see VERIFY_LOG]\n'
-        + s.slice(-VERIFY_TAIL_BYTES);
-    } else {
-      verifyExcerpt = s;
-    }
+    verifyExcerpt = _verifyExcerpt(verifyOutput, cwd);
   }
   const merged = checkpoint.mergeCheckpoint(
     taskId,

package/bin/np-tools/plan-milestone.cjs

@@ -95,6 +95,7 @@ async function _initPayload(mNum, cwd, opts) {
     const spawnSpecs = swarm.buildSpawnSpecs(
       { milestone: mNum, milestone_id: layout.mId(mNum), goal: def.goal || '' },
       swarmOpts.k,
+      { cwd },
     );
     let cacheHit = null;
     let cacheMiss = null;

package/bin/np-tools/research-phase.cjs

@@ -107,7 +107,7 @@ async function run(args, ctx) {
   const tmDetail = textMode.resolveTextModeDetail(cwd);
 
   const swarmOpts = swarm.resolveSwarmOpts(cwd);
-  const spawnSpecs = swarm.buildSpawnSpecs({ milestone: mNum, milestone_id: mIdStr, goal: def.goal || '' }, swarmOpts.k);
+  const spawnSpecs = swarm.buildSpawnSpecs({ milestone: mNum, milestone_id: mIdStr, goal: def.goal || '' }, swarmOpts.k, { cwd });
 
   let cacheHit = null;
   let cacheMiss = null;

package/bin/np-tools/spawn-headless.cjs

@@ -9,8 +9,35 @@ const { NubosPilotError, atomicWriteFileSync, appendJsonl, findProjectRoot } = r
 const runContext = require('../../lib/run-context.cjs');
 const safePath = require('../../lib/safe-path.cjs');
 const headlessGuard = require('../../lib/headless-guard.cjs');
+const compress = require('../../lib/compress.cjs');
+const elision = require('../../lib/elision.cjs');
+const elisionProxy = require('../../lib/elision-proxy.cjs');
+const steering = require('../../lib/output-steering.cjs');
+const logger = require('../../lib/logger.cjs').child('spawn-headless');
 const args = require('./_args.cjs');
 
+const PROXY_START_TIMEOUT_MS = 5000;
+
+function _startCompressionProxy(cwd) {
+  const upstream = process.env.ANTHROPIC_BASE_URL || '';
+  return new Promise((resolve, reject) => {
+    const proc = child_process.fork(path.join(__dirname, '_elision-proxy-entry.cjs'), [], {
+      env: Object.assign({}, process.env, { ELISION_PROXY_CWD: cwd, ELISION_PROXY_UPSTREAM: upstream }),
+      stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+    });
+    const timer = setTimeout(() => {
+      try { proc.kill(); } catch { /* already gone */ }
+      reject(new NubosPilotError('elision-proxy-start-timeout', 'compression proxy did not report ready in time', {}));
+    }, PROXY_START_TIMEOUT_MS);
+    proc.once('message', (m) => {
+      clearTimeout(timer);
+      if (m && m.ready) resolve({ proc, baseUrl: m.baseUrl });
+      else { try { proc.kill(); } catch { /* already gone */ } reject(new NubosPilotError('elision-proxy-start-failed', String(m && m.error), {})); }
+    });
+    proc.once('error', (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
 function _sha256(s) {
   return crypto.createHash('sha256').update(s == null ? '' : String(s)).digest('hex');
 }
@@ -159,6 +186,20 @@ function _composePrompt(agentBody, userPrompt) {
   return agentBody.trimEnd() + '\n\n---\n\n' + userPrompt.trimEnd() + '\n';
 }
 
+function _maybeCompressPrompt(prompt, cwd) {
+  const none = { prompt, stats: null };
+  const cx = elision.compressionContext(cwd);
+  if (!cx.enabled) return none;
+  try {
+    const out = compress.compressPrompt(prompt, { minBlockBytes: cx.minBlockBytes, store: cx.store });
+    if (!out || out.stats.blocks_compressed === 0) return none;
+    return { prompt: out.text, stats: out.stats };
+  } catch (err) {
+    logger.warn('compression skipped', { cause: err && err.message });
+    return none;
+  }
+}
+
 function _stripFrontmatter(md) {
   if (!md.startsWith('---\n')) return md;
   const end = md.indexOf('\n---\n', 4);
@@ -304,20 +345,15 @@ async function run(argv, ctx) {
   }
 
   const agentPath = _resolveAgentPath(agent, cwd);
-  const agentBody = _stripFrontmatter(fs.readFileSync(agentPath, 'utf-8'));
+  let agentBody = _stripFrontmatter(fs.readFileSync(agentPath, 'utf-8'));
+  const _os = elision.compressionContext(cwd).outputSteering;
+  if (_os && _os.enabled) agentBody = steering.enrichSystemPrompt(agentBody, _os.profile);
   const userPrompt = _readPromptFile(promptPath, cwd);
-  const composedPrompt = _composePrompt(agentBody, userPrompt);
+  let composedPrompt = _composePrompt(agentBody, userPrompt);
   const resolvedOutput = _ensureOutputDir(outputPath, cwd);
 
   const runId = runContext.getRunId();
 
-  // ADR-0021: off-host routing. If the agent routes to an openai-compat provider,
-  // run the nubos-pilot dispatch loop instead of `claude -p`, writing the result
-  // in the same {result,...} envelope `claude --output-format json` produces so the
-  // callers (review/extract parseXxxOutput → outer.result) parse it unchanged. The
-  // native path below is untouched. run() is async; the CLI dispatcher already
-  // awaits returned promises (handleRunResult), and the two in-process callers
-  // (review.cjs / extract.cjs) await runReview/runExtract.
   const resolveKind = context.resolveImpl || _defaultResolveKind;
   let routed;
   try { routed = resolveKind(agent, cwd); } catch { routed = { kind: 'native' }; }
@@ -329,6 +365,9 @@ async function run(argv, ctx) {
     });
   }
 
+  const compression = _maybeCompressPrompt(composedPrompt, cwd);
+  composedPrompt = compression.prompt;
+
   let lockRoot;
   try { lockRoot = findProjectRoot(cwd); }
   catch { lockRoot = cwd; }
@@ -344,6 +383,17 @@ async function run(argv, ctx) {
   const childEnv = _filterSpawnEnv(process.env);
   Object.assign(childEnv, headlessGuard.childSpawnEnv(process.env));
 
+  let proxyProc = null;
+  if (elisionProxy.proxyEnabled(cwd)) {
+    try {
+      const started = await _startCompressionProxy(cwd);
+      proxyProc = started.proc;
+      childEnv.ANTHROPIC_BASE_URL = started.baseUrl;
+    } catch (err) {
+      logger.warn('compression proxy unavailable; spawning without it', { cause: err && err.message });
+    }
+  }
+
   const bin = _claudeBinary();
   const claudeArgs = ['-p', '--output-format', 'json'];
   const startedAt = new Date().toISOString();
@@ -365,6 +415,7 @@ async function run(argv, ctx) {
       { bin, cause: err && err.code },
     );
   } finally {
+    if (proxyProc) { try { proxyProc.kill(); } catch { /* already exited */ } }
     lock.release();
   }
   if (result.error && result.error.code === 'ENOENT') {
@@ -406,6 +457,7 @@ async function run(argv, ctx) {
     tokens_in: claudeMeta.tokens_in == null ? null : claudeMeta.tokens_in,
     tokens_out: claudeMeta.tokens_out == null ? null : claudeMeta.tokens_out,
     payload_parse_ok: claudeMeta.parse_ok,
+    compression: compression.stats || null,
   };
   try { appendJsonl(spawnTrailPath, spawnRecord, { maxLineBytes: 16 * 1024, mode: 0o600 }); }
   catch (err) {
@@ -431,6 +483,7 @@ async function run(argv, ctx) {
     tokens_in: spawnRecord.tokens_in,
     tokens_out: spawnRecord.tokens_out,
     payload_parse_ok: spawnRecord.payload_parse_ok,
+    compression: compression.stats || null,
   };
   stdout.write(JSON.stringify(payload) + '\n');
   if (exitCode !== 0) return 2;

package/lib/cache-align.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+const UUID_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+const ISO_RE = /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+const JWT_RE = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/;
+const HEX_RE = /\b[0-9a-f]{32,64}\b/i;
+const VOLATILE = Object.freeze([
+  ['uuid', UUID_RE],
+  ['iso_datetime', ISO_RE],
+  ['jwt', JWT_RE],
+  ['hex_hash', HEX_RE],
+]);
+
+function _systemText(system) {
+  if (typeof system === 'string') return system;
+  if (Array.isArray(system)) {
+    return system.map((b) => (b && typeof b.text === 'string' ? b.text : '')).join('\n');
+  }
+  return '';
+}
+
+function detectVolatile(system) {
+  const text = _systemText(system);
+  const findings = [];
+  for (const [kind, re] of VOLATILE) {
+    const m = text.match(re);
+    if (m) findings.push({ kind, sample_len: m[0].length });
+  }
+  return findings;
+}
+
+function _sortKeys(v) {
+  if (Array.isArray(v)) return v.map(_sortKeys);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = _sortKeys(v[k]);
+    return out;
+  }
+  return v;
+}
+
+function _byCodepoint(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function normalizeTools(tools) {
+  return tools
+    .map(_sortKeys)
+    .map((t) => ({ t, name: String(t && t.name), body: JSON.stringify(t) }))
+    .sort((a, b) => _byCodepoint(a.name, b.name) || _byCodepoint(a.body, b.body))
+    .map((x) => x.t);
+}
+
+function _anyCacheControl(system, tools) {
+  if (Array.isArray(system) && system.some((b) => b && b.cache_control)) return true;
+  if (Array.isArray(tools) && tools.some((t) => t && t.cache_control)) return true;
+  return false;
+}
+
+function alignAnthropicBody(body) {
+  const findings = detectVolatile(body && body.system);
+  if (!body || !Array.isArray(body.tools) || body.tools.length === 0) {
+    return { body, findings, applied: false };
+  }
+  if (_anyCacheControl(body.system, body.tools)) {
+    return { body, findings, applied: false };
+  }
+  const tools = normalizeTools(body.tools);
+  const last = tools.length - 1;
+  tools[last] = Object.assign({}, tools[last], { cache_control: { type: 'ephemeral' } });
+  return { body: Object.assign({}, body, { tools }), findings, applied: true };
+}
+
+module.exports = {
+  detectVolatile,
+  normalizeTools,
+  alignAnthropicBody,
+};

package/lib/cache-align.test.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const ca = require('./cache-align.cjs');
+
+test('CA-1: detectVolatile flags UUID/ISO-date/JWT/hex in the system prompt', () => {
+  const sys = 'Run id 550e8400-e29b-41d4-a716-446655440000 at 2026-06-23T10:00:00Z '
+    + 'token eyJhbGc.eyJzdWI.sig hash d41d8cd98f00b204e9800998ecf8427e';
+  const kinds = ca.detectVolatile(sys).map((f) => f.kind).sort();
+  assert.deepEqual(kinds, ['hex_hash', 'iso_datetime', 'jwt', 'uuid']);
+});
+
+test('CA-2: detectVolatile reads an array-form system prompt and is clean when stable', () => {
+  assert.deepEqual(ca.detectVolatile([{ type: 'text', text: 'You are a stable agent.' }]), []);
+  assert.deepEqual(ca.detectVolatile('plain stable instructions'), []);
+});
+
+test('CA-3: normalizeTools sorts tools by name and recursively sorts schema keys; arrays keep order', () => {
+  const tools = [
+    { name: 'zeta', description: 'z', input_schema: { type: 'object', required: ['b', 'a'], properties: { y: {}, x: {} } } },
+    { name: 'alpha', description: 'a', input_schema: { properties: { n: {} }, type: 'object' } },
+  ];
+  const out = ca.normalizeTools(tools);
+  assert.deepEqual(out.map((t) => t.name), ['alpha', 'zeta']);
+  assert.deepEqual(Object.keys(out[1]), ['description', 'input_schema', 'name']);
+  assert.deepEqual(Object.keys(out[1].input_schema.properties), ['x', 'y']);
+  assert.deepEqual(out[1].input_schema.required, ['b', 'a']);
+});
+
+test('CA-4: alignAnthropicBody adds exactly one ephemeral breakpoint on the last tool and is idempotent', () => {
+  const body = { system: 'sys', tools: [{ name: 'b' }, { name: 'a' }], messages: [] };
+  const r1 = ca.alignAnthropicBody(body);
+  assert.equal(r1.applied, true);
+  assert.deepEqual(r1.body.tools.map((t) => t.name), ['a', 'b']);
+  assert.equal(r1.body.tools[0].cache_control, undefined);
+  assert.deepEqual(r1.body.tools[1].cache_control, { type: 'ephemeral' });
+  const r2 = ca.alignAnthropicBody(r1.body);
+  assert.equal(r2.applied, false, 'second pass is a no-op — breakpoint already present');
+  assert.equal(JSON.stringify(r2.body), JSON.stringify(r1.body), 'byte-identical second pass');
+});
+
+test('CA-4b: normalizeTools is byte-deterministic regardless of input order (codepoint, not locale)', () => {
+  const a = [{ name: 'get_A' }, { name: 'get-a' }, { name: 'get_a' }, { name: 'tool10' }, { name: 'tool2' }];
+  const b = a.slice().reverse();
+  assert.equal(JSON.stringify(ca.normalizeTools(a)), JSON.stringify(ca.normalizeTools(b)), 'order-independent, stable bytes');
+  assert.deepEqual(ca.normalizeTools(a).map((t) => t.name), ['get-a', 'get_A', 'get_a', 'tool10', 'tool2']);
+});
+
+test('CA-4c: duplicate/degenerate names still order deterministically via body tiebreak', () => {
+  const x = [{ name: 'x', id: 2 }, { name: 'x', id: 1 }];
+  assert.equal(JSON.stringify(ca.normalizeTools(x)), JSON.stringify(ca.normalizeTools(x.slice().reverse())));
+});
+
+test('CA-5: customer-placement-wins — a caller-set cache_control is never disturbed', () => {
+  const body = { tools: [{ name: 'z', cache_control: { type: 'ephemeral' } }, { name: 'a' }], messages: [] };
+  const r = ca.alignAnthropicBody(body);
+  assert.equal(r.applied, false);
+  assert.deepEqual(r.body.tools.map((t) => t.name), ['z', 'a'], 'tool order untouched when caller manages caching');
+});
+
+test('CA-6: no tools → no normalization, detection still runs', () => {
+  const body = { system: 'id 550e8400-e29b-41d4-a716-446655440000', messages: [] };
+  const r = ca.alignAnthropicBody(body);
+  assert.equal(r.applied, false);
+  assert.equal(r.body, body);
+  assert.deepEqual(r.findings.map((f) => f.kind), ['uuid']);
+});