@plune-ai/cli 0.27.0 → 0.28.0

package/dist/index.cjs

@@ -54,6 +54,10 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.15_tsx@4.22.4_typescript@5.9.3_yaml@2.9.0/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
 // src/cli/commands/run.ts
 var fs5 = __toESM(require("fs"), 1);
 var path4 = __toESM(require("path"), 1);
@@ -508,7 +512,8 @@ function makeAnthropicProvider(config, env, pricing) {
           usage: {
             input_tokens: res.usage.input_tokens,
             output_tokens: res.usage.output_tokens
-          }
+          },
+          ...res.stop_reason === "max_tokens" ? { finish_reason: "length" } : res.stop_reason !== null && res.stop_reason !== void 0 ? { finish_reason: res.stop_reason } : {}
         };
       } catch (err) {
         throw normalizeProviderError(err, apiKey, ENV_VAR);
@@ -555,8 +560,11 @@ function makeOpenAiCompatibleProvider(opts) {
           { max_retries: maxRetries }
         );
         const reportedCost = reportsCost ? res.usage?.cost : void 0;
+        const choice = res.choices[0];
+        const finish = choice?.error !== void 0 ? "error" : choice?.finish_reason;
         return {
-          output: res.choices[0]?.message?.content ?? "",
+          output: choice?.message?.content ?? "",
+          ...typeof finish === "string" ? { finish_reason: finish } : {},
           usage: {
             input_tokens: res.usage?.prompt_tokens ?? 0,
             output_tokens: res.usage?.completion_tokens ?? 0
@@ -691,21 +699,110 @@ function getDefaultEmbedder() {
 }
 
 // src/cache/cache.ts
-var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var import_node_module = require("module");
+
+// src/util/hash.ts
+var import_node_crypto = require("crypto");
+
+// src/util/canonical-json.ts
+function normalizeValue(value) {
+  if (value === null) return null;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!isFinite(value)) {
+      throw new Error(
+        `canonicalJson: non-finite number rejected: ${String(value)}`
+      );
+    }
+    return value === 0 ? 0 : value;
+  }
+  if (typeof value === "string") {
+    return value.normalize("NFC");
+  }
+  if (Array.isArray(value)) {
+    return value.map(normalizeValue);
+  }
+  if (typeof value === "object") {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) {
+      const name = value.constructor?.name ?? "unknown";
+      throw new Error(
+        `canonicalJson: unsupported non-plain object (${name}) \u2014 only plain objects, arrays, and primitives are serializable`
+      );
+    }
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = normalizeValue(obj[key]);
+    }
+    return sorted;
+  }
+  throw new Error(
+    `canonicalJson: unsupported value type: ${typeof value}`
+  );
+}
+function canonicalJson(value) {
+  return JSON.stringify(normalizeValue(value));
+}
+
+// src/util/hash.ts
+function sha256(input) {
+  return (0, import_node_crypto.createHash)("sha256").update(input, "utf8").digest("hex");
+}
+var CACHE_POLICY_VERSION = 1;
+function cacheKey(inputs, policyVersion = CACHE_POLICY_VERSION) {
+  const { provider, model, temperature, max_tokens, prompt_resolved } = inputs;
+  return sha256(
+    canonicalJson({ provider, model, temperature, max_tokens, prompt_resolved, policy: policyVersion })
+  );
+}
+function configHash(config) {
+  return sha256(canonicalJson(config));
+}
+
+// src/cache/cache.ts
 var SCHEMA_VERSION = 1;
 var META_DDL = "CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);";
 var COMPLETIONS_DDL = "CREATE TABLE IF NOT EXISTS completions (cache_key TEXT PRIMARY KEY, output TEXT NOT NULL, input_tokens INTEGER NOT NULL, output_tokens INTEGER NOT NULL, created_at INTEGER NOT NULL);";
+var UNCACHEABLE_FINISH = /* @__PURE__ */ new Set(["length", "max_tokens", "error", "content_filter", "pause_turn"]);
+function isCacheable(res) {
+  if (res.output.trim() === "") return false;
+  return res.finish_reason === void 0 || !UNCACHEABLE_FINISH.has(res.finish_reason);
+}
+var missingNoted = false;
+function loadDatabase() {
+  try {
+    return (0, import_node_module.createRequire)(importMetaUrl)("better-sqlite3");
+  } catch {
+    if (!missingNoted) {
+      missingNoted = true;
+      console.error(
+        "plune: completion cache disabled (better-sqlite3 is not installed or failed to load). Reinstall with a C++ toolchain and Python available, or ignore: runs work without the cache."
+      );
+    }
+    return void 0;
+  }
+}
 function openCache(file, opts = {}) {
   const now = opts.now ?? Date.now;
+  const Database = loadDatabase();
+  if (Database === void 0) return new NoOpCache();
   try {
-    const db = new import_better_sqlite3.default(file);
+    const db = new Database(file);
     try {
       ensureSchema(db);
     } catch (err) {
       db.close();
       throw err;
     }
-    return new SqliteCache(db, now);
+    let stale;
+    try {
+      stale = markPolicy(db, opts.policyVersion ?? CACHE_POLICY_VERSION);
+    } catch (err) {
+      db.close();
+      throw err;
+    }
+    return new SqliteCache(db, now, stale);
   } catch {
     return new NoOpCache();
   }
@@ -720,17 +817,33 @@ function ensureSchema(db) {
     db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("schema_version", current);
   }
 }
+function markPolicy(db, version) {
+  const current = String(version);
+  const stored = db.prepare("SELECT value FROM meta WHERE key = 'policy_version'").get()?.value;
+  if (stored === current) return 0;
+  return db.transaction(() => {
+    const { n } = db.prepare("SELECT COUNT(*) AS n FROM completions").get();
+    db.exec("DELETE FROM completions");
+    db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("policy_version", current);
+    return n;
+  })();
+}
 var SqliteCache = class {
-  constructor(db, now) {
+  constructor(db, now, staleEntries) {
     this.db = db;
     this.now = now;
+    this.staleEntries = staleEntries;
   }
   db;
   now;
+  staleEntries;
   get(key, opts = {}) {
     try {
       const row = this.db.prepare("SELECT output, input_tokens, output_tokens, created_at FROM completions WHERE cache_key = ?").get(key);
       if (row === void 0) return void 0;
+      if (typeof row.output !== "string" || !Number.isFinite(row.input_tokens) || !Number.isFinite(row.output_tokens) || !Number.isFinite(row.created_at)) {
+        return void 0;
+      }
       if (opts.maxAgeMs !== void 0 && this.now() - row.created_at > opts.maxAgeMs) {
         return void 0;
       }
@@ -756,6 +869,12 @@ var SqliteCache = class {
     } catch {
     }
   }
+  delete(key) {
+    try {
+      this.db.prepare("DELETE FROM completions WHERE cache_key = ?").run(key);
+    } catch {
+    }
+  }
   clear() {
     try {
       this.db.exec("DELETE FROM completions");
@@ -772,6 +891,8 @@ var NoOpCache = class {
   }
   set() {
   }
+  delete() {
+  }
   clear() {
   }
   close() {
@@ -782,60 +903,72 @@ var NoOpCache = class {
 var fs3 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
 
-// src/util/hash.ts
-var import_node_crypto = require("crypto");
-
-// src/util/canonical-json.ts
-function normalizeValue(value) {
-  if (value === null) return null;
-  if (typeof value === "boolean") return value;
-  if (typeof value === "number") {
-    if (!isFinite(value)) {
-      throw new Error(
-        `canonicalJson: non-finite number rejected: ${String(value)}`
-      );
-    }
-    return value === 0 ? 0 : value;
-  }
-  if (typeof value === "string") {
-    return value.normalize("NFC");
+// src/assertions/json-extract.ts
+function extractJson(output, mode) {
+  if (mode === "strict") {
+    return tryParse(output.trim());
   }
-  if (Array.isArray(value)) {
-    return value.map(normalizeValue);
+  const fenced = extractFencedBlock(output);
+  if (fenced !== null) {
+    const r = tryParse(fenced);
+    if (r.ok) return r;
   }
-  if (typeof value === "object") {
-    const proto = Object.getPrototypeOf(value);
-    if (proto !== null && proto !== Object.prototype) {
-      const name = value.constructor?.name ?? "unknown";
-      throw new Error(
-        `canonicalJson: unsupported non-plain object (${name}) \u2014 only plain objects, arrays, and primitives are serializable`
-      );
-    }
-    const obj = value;
-    const sorted = {};
-    for (const key of Object.keys(obj).sort()) {
-      sorted[key] = normalizeValue(obj[key]);
-    }
-    return sorted;
+  for (const run of balancedRuns(output)) {
+    const r = tryParse(run);
+    if (r.ok) return r;
   }
-  throw new Error(
-    `canonicalJson: unsupported value type: ${typeof value}`
-  );
+  return { ok: false };
 }
-function canonicalJson(value) {
-  return JSON.stringify(normalizeValue(value));
+function tryParse(s) {
+  try {
+    return { ok: true, value: JSON.parse(s) };
+  } catch {
+    return { ok: false };
+  }
 }
-
-// src/util/hash.ts
-function sha256(input) {
-  return (0, import_node_crypto.createHash)("sha256").update(input, "utf8").digest("hex");
+function extractFencedBlock(s) {
+  const m = s.match(/```(?:json)?\s*\n?([\s\S]*?)```/i);
+  return m?.[1]?.trim() ?? null;
 }
-function cacheKey(inputs) {
-  const { provider, model, temperature, max_tokens, prompt_resolved } = inputs;
-  return sha256(canonicalJson({ provider, model, temperature, max_tokens, prompt_resolved }));
+function* balancedRuns(s) {
+  let i = 0;
+  while (i < s.length) {
+    const rel = s.slice(i).search(/[{[]/);
+    if (rel === -1) return;
+    const start = i + rel;
+    const run = balancedFrom(s, start);
+    if (run === null) {
+      i = start + 1;
+    } else {
+      yield run;
+      i = start + run.length;
+    }
+  }
 }
-function configHash(config) {
-  return sha256(canonicalJson(config));
+function balancedFrom(s, start) {
+  const open = s[start];
+  const close = open === "{" ? "}" : "]";
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < s.length; i++) {
+    const ch = s[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === open) {
+      depth++;
+    } else if (ch === close) {
+      depth--;
+      if (depth === 0) return s.slice(start, i + 1);
+    }
+  }
+  return null;
 }
 
 // src/assertions/interpolate.ts
@@ -911,76 +1044,6 @@ var containsAll = {
 
 // src/assertions/json-schema.ts
 var import_ajv = require("ajv");
-
-// src/assertions/json-extract.ts
-function extractJson(output, mode) {
-  if (mode === "strict") {
-    return tryParse(output.trim());
-  }
-  const fenced = extractFencedBlock(output);
-  if (fenced !== null) {
-    const r = tryParse(fenced);
-    if (r.ok) return r;
-  }
-  for (const run of balancedRuns(output)) {
-    const r = tryParse(run);
-    if (r.ok) return r;
-  }
-  return { ok: false };
-}
-function tryParse(s) {
-  try {
-    return { ok: true, value: JSON.parse(s) };
-  } catch {
-    return { ok: false };
-  }
-}
-function extractFencedBlock(s) {
-  const m = s.match(/```(?:json)?\s*\n?([\s\S]*?)```/i);
-  return m?.[1]?.trim() ?? null;
-}
-function* balancedRuns(s) {
-  let i = 0;
-  while (i < s.length) {
-    const rel = s.slice(i).search(/[{[]/);
-    if (rel === -1) return;
-    const start = i + rel;
-    const run = balancedFrom(s, start);
-    if (run === null) {
-      i = start + 1;
-    } else {
-      yield run;
-      i = start + run.length;
-    }
-  }
-}
-function balancedFrom(s, start) {
-  const open = s[start];
-  const close = open === "{" ? "}" : "]";
-  let depth = 0;
-  let inString = false;
-  let escaped = false;
-  for (let i = start; i < s.length; i++) {
-    const ch = s[i];
-    if (inString) {
-      if (escaped) escaped = false;
-      else if (ch === "\\") escaped = true;
-      else if (ch === '"') inString = false;
-      continue;
-    }
-    if (ch === '"') {
-      inString = true;
-    } else if (ch === open) {
-      depth++;
-    } else if (ch === close) {
-      depth--;
-      if (depth === 0) return s.slice(start, i + 1);
-    }
-  }
-  return null;
-}
-
-// src/assertions/json-schema.ts
 var jsonSchema = {
   run(ctx) {
     const mode = ctx.params.extract ?? "auto";
@@ -1340,6 +1403,12 @@ var RunConfigError = class extends Error {
     this.name = "RunConfigError";
   }
 };
+var CACHE_MISS_CODE = "CACHE_MISS";
+function answerParses(output, assertions) {
+  return assertions.every(
+    (a) => a.type !== "json-schema" || extractJson(output, a.extract ?? "auto").ok
+  );
+}
 function resolvePrompt(template, vars) {
   return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_match, key) => {
     if (!(key in vars)) {
@@ -1367,17 +1436,35 @@ async function runRow(p) {
     const usage2 = { ...est, cost_usd: p.provider.estimateCost(est).cost_usd };
     return { vars: p.row.vars, output: null, cached: false, usage: usage2, assertions: [] };
   }
-  const key = cacheKey({
-    provider: p.providerConfig.type,
-    model: p.providerConfig.model,
-    temperature: temperature ?? 0,
-    max_tokens: maxTokens,
-    prompt_resolved: prompt5
-  });
+  const key = cacheKey(
+    {
+      provider: p.providerConfig.type,
+      model: p.providerConfig.model,
+      temperature: temperature ?? 0,
+      max_tokens: maxTokens,
+      prompt_resolved: prompt5
+    },
+    p.policyVersion
+  );
   let output;
   let usage;
   let cached = false;
-  const hit = p.noCache ? void 0 : p.cache.get(key);
+  let cacheSaved;
+  let hit = p.noCache ? void 0 : p.cache.get(key, p.cacheMaxAgeMs !== void 0 ? { maxAgeMs: p.cacheMaxAgeMs } : {});
+  if (hit !== void 0 && !answerParses(hit.output, p.assertions)) {
+    if (p.cacheStrict !== true) p.cache.delete(key);
+    hit = void 0;
+  }
+  if (hit === void 0 && p.cacheStrict === true) {
+    return {
+      vars: p.row.vars,
+      output: null,
+      cached: false,
+      latency_ms: p.now() - t0,
+      error: { code: CACHE_MISS_CODE, message: "no usable cache entry (--cache-strict)" },
+      assertions: []
+    };
+  }
   if (hit !== void 0) {
     output = hit.output;
     cached = true;
@@ -1386,6 +1473,11 @@ async function runRow(p) {
       output_tokens: hit.usage.output_tokens,
       cost_usd: 0
     };
+    cacheSaved = {
+      input_tokens: hit.usage.input_tokens,
+      output_tokens: hit.usage.output_tokens,
+      cost_usd: p.provider.estimateCost(hit.usage).cost_usd
+    };
   } else {
     try {
       const res = await p.provider.complete({
@@ -1403,7 +1495,9 @@ async function runRow(p) {
         // lets a config pricing override win, else falls back to the table estimate (ADR-PRC01).
         cost_usd: p.provider.estimateCost(res.usage, res.cost_usd).cost_usd
       };
-      if (!p.noCache) p.cache.set(key, res);
+      if (!p.noCache && isCacheable(res) && answerParses(res.output, p.assertions)) {
+        p.cache.set(key, res);
+      }
     } catch (err) {
       return {
         vars: p.row.vars,
@@ -1449,6 +1543,7 @@ async function runRow(p) {
     cached,
     usage: finalUsage,
     latency_ms: p.now() - t0,
+    ...cacheSaved !== void 0 ? { cache_saved: cacheSaved } : {},
     ...assertionError !== void 0 ? { error: assertionError } : {},
     assertions: records
   };
@@ -1483,19 +1578,41 @@ function summarize(evals, durationMs) {
     cost_usd: 0,
     duration_ms: durationMs
   };
+  const cache = {
+    from_cache: 0,
+    from_model: 0,
+    missed: 0,
+    errored: 0,
+    saved: { input_tokens: 0, output_tokens: 0, cost_usd: 0 }
+  };
   for (const ev of evals) {
     for (const row of ev.rows) {
       summary.total += 1;
       summary[rowStatus(row)] += 1;
       summary.cost_usd += row.usage?.cost_usd ?? 0;
+      if (row.cached) {
+        cache.from_cache += 1;
+        cache.saved.input_tokens += row.cache_saved?.input_tokens ?? 0;
+        cache.saved.output_tokens += row.cache_saved?.output_tokens ?? 0;
+        cache.saved.cost_usd += row.cache_saved?.cost_usd ?? 0;
+      } else if (row.error?.code === CACHE_MISS_CODE) cache.missed += 1;
+      else if (row.output !== null) cache.from_model += 1;
+      else if (row.error !== void 0) cache.errored += 1;
     }
   }
-  return summary;
+  return { ...summary, cache };
 }
 async function runOrchestration(config, options, deps) {
+  const noCache = options.noCache ?? false;
+  const cacheStrict = options.cacheStrict ?? false;
+  if (noCache && cacheStrict) {
+    throw new RunConfigError("--no-cache and --cache-strict cannot be used together");
+  }
+  if (noCache && options.cacheMaxAgeMs !== void 0) {
+    throw new RunConfigError("--no-cache and --cache-max-age cannot be used together");
+  }
   const started = deps.now();
   const dryRun = options.dryRun ?? false;
-  const noCache = options.noCache ?? false;
   const evalResults = [];
   const prepared = selectEvals(config.evals, options.only).map((ev) => {
     const template = resolveTemplate(ev, deps.baseDir);
@@ -1522,7 +1639,9 @@ async function runOrchestration(config, options, deps) {
         cache: deps.cache,
         now: deps.now,
         dryRun,
-        noCache
+        noCache,
+        cacheStrict,
+        ...options.cacheMaxAgeMs !== void 0 ? { cacheMaxAgeMs: options.cacheMaxAgeMs } : {}
       })
     );
     const passed = rowResults.every((r) => rowStatus(r) === "passed");
@@ -1555,6 +1674,7 @@ function loadDataset(ref, baseDir) {
 
 // src/cli/commands/run.ts
 var NOOP_CACHE = { get: () => void 0, set: () => {
+}, delete: () => {
 }, clear: () => {
 }, close: () => {
 } };
@@ -1591,6 +1711,11 @@ async function handleRun(options, depsFactory) {
   const factory = depsFactory ?? ((c, d) => buildRealDeps(c, d, options.dryRun));
   const deps = factory(config, baseDir);
   try {
+    const stale = deps.cache.staleEntries ?? 0;
+    if (stale > 0) {
+      process.stderr.write(`cache policy changed, ${stale} entries are stale (dropped)
+`);
+    }
     const result = await runOrchestration(
       config,
       {
@@ -1598,7 +1723,9 @@ async function handleRun(options, depsFactory) {
         ...options.only !== void 0 ? { only: options.only } : {},
         ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {},
         ...options.noCache !== void 0 ? { noCache: options.noCache } : {},
-        ...options.bail !== void 0 ? { bail: options.bail } : {}
+        ...options.bail !== void 0 ? { bail: options.bail } : {},
+        ...options.cacheStrict === true ? { cacheStrict: true } : {},
+        ...options.cacheMaxAgeMs !== void 0 ? { cacheMaxAgeMs: options.cacheMaxAgeMs } : {}
       },
       deps
     );
@@ -1645,6 +1772,7 @@ var rowResultSchema = import_zod3.z.object({
   latency_ms: import_zod3.z.number().optional(),
   error: runErrorSchema.optional(),
   assertions: import_zod3.z.array(assertionResultRecordSchema2),
+  cache_saved: import_zod3.z.object({ input_tokens: import_zod3.z.number(), output_tokens: import_zod3.z.number(), cost_usd: import_zod3.z.number() }).optional(),
   /** ADR 0045. Optional and additive — the same enum the platform validates on `POST /v1/runs`. */
   inconclusive: import_zod3.z.enum(ROW_INCONCLUSIVE).optional()
 });
@@ -1657,7 +1785,14 @@ var summarySchema = import_zod3.z.object({
   blocked: import_zod3.z.number().optional(),
   skipped: import_zod3.z.number().optional(),
   cost_usd: import_zod3.z.number(),
-  duration_ms: import_zod3.z.number()
+  duration_ms: import_zod3.z.number(),
+  cache: import_zod3.z.object({
+    from_cache: import_zod3.z.number(),
+    from_model: import_zod3.z.number(),
+    missed: import_zod3.z.number(),
+    errored: import_zod3.z.number(),
+    saved: import_zod3.z.object({ input_tokens: import_zod3.z.number(), output_tokens: import_zod3.z.number(), cost_usd: import_zod3.z.number() })
+  }).optional()
 });
 var evalResultSchema = import_zod3.z.object({
   id: import_zod3.z.string(),

package/dist/index.d.cts

@@ -15,6 +15,24 @@ interface Summary {
     skipped?: number;
     cost_usd: number;
     duration_ms: number;
+    /** plune-ai/plune#1696. Where the answers came from. Optional and additive; absent in older runs. */
+    cache?: CacheSummary;
+}
+/**
+ * `from_cache` rows were answered by the store, `from_model` by a model call, `missed` had no entry
+ * under `--cache-strict` and were not answered. The `saved` totals are the sum of the rows' `cache_saved`.
+ */
+interface CacheSummary {
+    from_cache: number;
+    from_model: number;
+    missed: number;
+    /** Rows the provider failed on: answered by neither, so the four counts add up to `total` (dry-run rows aside). */
+    errored: number;
+    saved: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
 }
 interface AssertionResultRecord {
     type: string;
@@ -87,6 +105,12 @@ interface RowResult {
     latency_ms?: number;
     error?: RunError;
     assertions: AssertionResultRecord[];
+    /** plune-ai/plune#1696. On a cache hit: what the call would have cost. Optional and additive. */
+    cache_saved?: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
     /**
      * ADR 0045. Say it when the test was never judged, rather than letting `failed` stand for both
      * "the environment broke" and "the code is wrong".
@@ -231,6 +255,11 @@ interface CompletionResponse {
      * estimated downstream (ADR-PRC02). Additive + optional: existing providers omit it.
      */
     cost_usd?: number;
+    /**
+     * Why the model stopped, normalised: `length` (hit the token limit), `error` or `content_filter`
+     * mark an answer the cache must not keep. Absent when the provider does not say. Optional and additive.
+     */
+    finish_reason?: string;
 }
 interface CostEstimate {
     cost_usd: number;
@@ -260,6 +289,10 @@ interface Cache {
         maxAgeMs?: number;
     }): CompletionResponse | undefined;
     set(key: string, value: CompletionResponse): void;
+    /** Remove one entry (a cached answer that turned out unusable). Best-effort. */
+    delete(key: string): void;
+    /** Entries left by an older policy version, found when the store was opened (0 when none or unknown). */
+    readonly staleEntries?: number;
     clear(): void;
     close(): void;
 }
@@ -280,6 +313,9 @@ interface RunOptions {
     concurrency?: number;
     noCache?: boolean;
     bail?: boolean;
+    cacheStrict?: boolean;
+    /** Milliseconds; parsed from `--cache-max-age` by the caller. */
+    cacheMaxAgeMs?: number;
 }
 declare function handleRun(options: RunOptions, depsFactory?: (config: Config, baseDir: string) => RunDeps): Promise<RunResult>;
 
@@ -449,6 +485,17 @@ declare const runResultSchema: z.ZodObject<{
         skipped: z.ZodOptional<z.ZodNumber>;
         cost_usd: z.ZodNumber;
         duration_ms: z.ZodNumber;
+        cache: z.ZodOptional<z.ZodObject<{
+            from_cache: z.ZodNumber;
+            from_model: z.ZodNumber;
+            missed: z.ZodNumber;
+            errored: z.ZodNumber;
+            saved: z.ZodObject<{
+                input_tokens: z.ZodNumber;
+                output_tokens: z.ZodNumber;
+                cost_usd: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     evals: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -477,6 +524,11 @@ declare const runResultSchema: z.ZodObject<{
                     passed: z.ZodBoolean;
                 }, z.core.$strip>>>;
             }, z.core.$strip>>;
+            cache_saved: z.ZodOptional<z.ZodObject<{
+                input_tokens: z.ZodNumber;
+                output_tokens: z.ZodNumber;
+                cost_usd: z.ZodNumber;
+            }, z.core.$strip>>;
             inconclusive: z.ZodOptional<z.ZodEnum<{
                 blocked: "blocked";
                 skipped: "skipped";