agent-nuvira 3.3.3 → 3.3.4

package/dist/learning/seeded-bugs.js

@@ -0,0 +1,535 @@
+/**
+ * WS7 (#29) — the seeded-bug benchmark.
+ *
+ * WHY THIS IS TEST INFRASTRUCTURE AND NOT A MATRIX ROW. `src/parity/matrix.ts`
+ * says it in one line: the seeded-bug benchmark is not a capability a surface can
+ * have, so it has no cells and no parity verdict of its own. What it has is a job —
+ * measure whether the agent can FIND and FIX a defect it was not told about, which
+ * is the thing a coding agent is for and the thing the M2b suite could only
+ * approximate: M2b tasks are written by hand and graded by hidden tests, but
+ * nothing proves the task was BROKEN before the agent ran, so a task that already
+ * passed measured nothing.
+ *
+ * THE PROPERTY THAT MAKES THIS A BENCHMARK RATHER THAN A TASK LIST. Every seeded
+ * bug is declared TWICE — the broken workspace the agent receives, and the same
+ * workspace after a reference fix — and `verifySeededBug` runs the checks against
+ * both. The checks must FAIL on the seed (and say so in their own words) and PASS
+ * after the fix. A seed that already passes its checks, or a check that cannot
+ * pass even when fixed, fails verification and is NOT scored: `runSeededSuite`
+ * verifies every task before it runs a single model call. `nuvira eval
+ * verify-seeds` exposes the same verification directly, so the ratchet is
+ * runnable from a terminal and in CI without a provider.
+ *
+ * WHAT 'FAILING' HAS TO MEAN. A check that exits non-zero because it crashed —
+ * a syntax error, a missing module — would satisfy a naive verification while
+ * proving nothing about the bug. So a seed counts as genuinely broken only when
+ * its check exits non-zero AND prints the failure marker its own assertions
+ * print (`FAIL`). Combined with "the same check passes once the fix is applied",
+ * that pins both ends: the check is well-formed, and it is the DEFECT that makes
+ * it fail.
+ *
+ * PLAIN NODE, ON PURPOSE. Every seed is a CommonJS `.js` file with a `.js` test
+ * script and no dependencies, so verification is deterministic, offline, and
+ * needs nothing but the `node` already running the suite. (A future Python seed
+ * would have to be gated on an interpreter actually being present rather than
+ * assumed — the honest version of "we also test Python".)
+ *
+ * Deliberately NOT measured here: collateral damage to files the fix should not
+ * touch is scored from a diff of the workspace against the seed
+ * (`src/learning/seeded-benchmark.ts`), not from reference patterns, because
+ * "this file still contains line X" is a weaker claim than "this file is
+ * unchanged" and the benchmark should not make the weak one.
+ */
+import { execSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** The exact request every seeded task makes — uniform, so the score compares competence. */
+export function seededGoal(bug) {
+    const commands = bug.checks.map((c) => `\`${c.command}\``).join(' and ');
+    return (`${commands} fails in this project. Diagnose the defect in the source and fix it so the ` +
+        `check passes. Do not modify the check file, and do not change any file that is not ` +
+        `responsible for the failure.`);
+}
+const RANGE_TEST = `const assert = require('node:assert');
+const { range } = require('../src/range.js');
+try {
+  assert.deepStrictEqual(range(3), [0, 1, 2]);
+  assert.deepStrictEqual(range(0), []);
+  console.log('ok');
+} catch (err) {
+  console.error('FAIL: ' + err.message);
+  process.exit(1);
+}
+`;
+const TOP_SCORES_TEST = `const assert = require('node:assert');
+const { topScores } = require('../src/top-scores.js');
+try {
+  assert.deepStrictEqual(topScores([10, 9, 100], 2), [100, 10]);
+  assert.deepStrictEqual(topScores([5, 5, 1], 2), [5, 5]);
+  console.log('ok');
+} catch (err) {
+  console.error('FAIL: ' + err.message);
+  process.exit(1);
+}
+`;
+const SUM_ASYNC_TEST = `const assert = require('node:assert');
+const { sumAsync } = require('../src/sum-async.js');
+(async () => {
+  try {
+    assert.strictEqual(await sumAsync([1, 2, 3]), 6);
+    assert.strictEqual(await sumAsync([]), 0);
+    console.log('ok');
+  } catch (err) {
+    console.error('FAIL: ' + err.message);
+    process.exit(1);
+  }
+})();
+`;
+const FORMAT_AMOUNT_TEST = `const assert = require('node:assert');
+const { formatAmount } = require('../src/format-amount.js');
+try {
+  assert.strictEqual(formatAmount(12.5), '$12.50');
+  assert.strictEqual(formatAmount(0), '$0.00');
+  assert.strictEqual(formatAmount(null), '—');
+  console.log('ok');
+} catch (err) {
+  console.error('FAIL: ' + err.message);
+  process.exit(1);
+}
+`;
+const CLONE_CONFIG_TEST = `const assert = require('node:assert');
+const { cloneConfig } = require('../src/clone-config.js');
+try {
+  const original = { name: 'svc', limits: { max: 10 } };
+  const copy = cloneConfig(original);
+  copy.limits.max = 99;
+  assert.strictEqual(original.limits.max, 10, 'the original object was mutated through the copy');
+  assert.strictEqual(copy.name, 'svc');
+  console.log('ok');
+} catch (err) {
+  console.error('FAIL: ' + err.message);
+  process.exit(1);
+}
+`;
+const ADD_TAG_TEST = `const assert = require('node:assert');
+const { addTag } = require('../src/add-tag.js');
+try {
+  const tags = ['a'];
+  const next = addTag(tags, 'b');
+  assert.deepStrictEqual(next, ['a', 'b']);
+  assert.deepStrictEqual(tags, ['a'], 'addTag mutated the caller array');
+  console.log('ok');
+} catch (err) {
+  console.error('FAIL: ' + err.message);
+  process.exit(1);
+}
+`;
+const AVERAGE_TEST = `const assert = require('node:assert');
+const { averageOf } = require('../src/average-of.js');
+try {
+  assert.strictEqual(averageOf([10, null, 20]), 15);
+  assert.strictEqual(averageOf([null]), 0);
+  console.log('ok');
+} catch (err) {
+  console.error('FAIL: ' + err.message);
+  process.exit(1);
+}
+`;
+/**
+ * The suite.
+ *
+ * Each entry is a real defect with a real fix, small enough that a strong model
+ * can find it from the failing check and that the reference fix is unambiguous.
+ * The axes are the ones that actually bite in production code: an inclusive bound,
+ * a comparator that was never given, an async callback in a synchronous-looking
+ * call, a falsy guard that eats a legitimate zero, a copy that is only one level
+ * deep, a helper that mutates its caller's data, and a denominator that was not
+ * updated with the filter beside it.
+ */
+export const SEEDED_BUGS = [
+    {
+        id: 'seed-range-off-by-one',
+        title: 'Range helper returns one element too many',
+        axis: 'boundary',
+        difficulty: 'easy',
+        bug: '`for (let i = 0; i <= n; i += 1)` makes `range(n)` produce n+1 elements; the bound must be exclusive.',
+        files: [
+            {
+                path: 'src/range.js',
+                content: `function range(n) {
+  const out = [];
+  for (let i = 0; i <= n; i += 1) out.push(i);
+  return out;
+}
+
+module.exports = { range };
+`,
+            },
+            { path: 'test/range.test.js', content: RANGE_TEST },
+        ],
+        fixedFiles: [
+            {
+                path: 'src/range.js',
+                content: `function range(n) {
+  const out = [];
+  for (let i = 0; i < n; i += 1) out.push(i);
+  return out;
+}
+
+module.exports = { range };
+`,
+            },
+        ],
+        target: 'src/range.js',
+        checks: [{ file: 'test/range.test.js', command: 'node test/range.test.js' }],
+        detectionSignals: ['off-by-one', 'off by one', 'inclusive', 'exclusive', '<='],
+        tokenBudget: 20_000,
+    },
+    {
+        id: 'seed-top-scores-lexical-sort',
+        title: 'Top scores sorted as strings',
+        axis: 'comparator',
+        difficulty: 'easy',
+        bug: '`scores.sort()` sorts lexically without a comparator, so 100 ranks below 9. The fix must also stop mutating the caller array.',
+        files: [
+            {
+                path: 'src/top-scores.js',
+                content: `function topScores(scores, n) {
+  return scores.sort().slice(0, n);
+}
+
+module.exports = { topScores };
+`,
+            },
+            { path: 'test/top-scores.test.js', content: TOP_SCORES_TEST },
+        ],
+        fixedFiles: [
+            {
+                path: 'src/top-scores.js',
+                content: `function topScores(scores, n) {
+  return [...scores].sort((a, b) => b - a).slice(0, n);
+}
+
+module.exports = { topScores };
+`,
+            },
+        ],
+        target: 'src/top-scores.js',
+        checks: [{ file: 'test/top-scores.test.js', command: 'node test/top-scores.test.js' }],
+        detectionSignals: ['lexicograph', 'string', 'comparator', 'numeric'],
+        tokenBudget: 20_000,
+    },
+    {
+        id: 'seed-sum-async-for-each',
+        title: 'Async callback in a synchronous-looking forEach',
+        axis: 'async',
+        difficulty: 'medium',
+        bug: '`values.forEach(async …)` never awaits the callbacks, so the function resolves before the calls finish and returns the initial 0.',
+        files: [
+            {
+                path: 'src/sum-async.js',
+                content: `async function sumAsync(values) {
+  let total = 0;
+  values.forEach(async (value) => {
+    total += await Promise.resolve(value);
+  });
+  return total;
+}
+
+module.exports = { sumAsync };
+`,
+            },
+            { path: 'test/sum-async.test.js', content: SUM_ASYNC_TEST },
+        ],
+        fixedFiles: [
+            {
+                path: 'src/sum-async.js',
+                content: `async function sumAsync(values) {
+  let total = 0;
+  for (const value of values) {
+    total += await Promise.resolve(value);
+  }
+  return total;
+}
+
+module.exports = { sumAsync };
+`,
+            },
+        ],
+        target: 'src/sum-async.js',
+        checks: [{ file: 'test/sum-async.test.js', command: 'node test/sum-async.test.js' }],
+        detectionSignals: ['forall', 'not awaited', 'await', 'race', 'synchronous'],
+        tokenBudget: 20_000,
+    },
+    {
+        id: 'seed-format-amount-falsy-zero',
+        title: 'A falsy guard swallows a legitimate zero',
+        axis: 'truthiness',
+        difficulty: 'easy',
+        bug: 'A falsy guard (if (!amount)) treats 0 as missing; the guard must test for null/undefined instead, while null must still read as an em dash.',
+        files: [
+            {
+                path: 'src/format-amount.js',
+                content: `function formatAmount(amount) {
+  if (!amount) return '—';
+  return '$' + amount.toFixed(2);
+}
+
+module.exports = { formatAmount };
+`,
+            },
+            { path: 'test/format-amount.test.js', content: FORMAT_AMOUNT_TEST },
+        ],
+        fixedFiles: [
+            {
+                path: 'src/format-amount.js',
+                content: `function formatAmount(amount) {
+  if (amount === null || amount === undefined) return '—';
+  return '$' + amount.toFixed(2);
+}
+
+module.exports = { formatAmount };
+`,
+            },
+        ],
+        target: 'src/format-amount.js',
+        checks: [{ file: 'test/format-amount.test.js', command: 'node test/format-amount.test.js' }],
+        detectionSignals: ['falsy', 'truthy', 'zero', '!amount', 'null'],
+        tokenBudget: 20_000,
+    },
+    {
+        id: 'seed-clone-config-shallow',
+        title: 'Config clone is only one level deep',
+        axis: 'aliasing',
+        difficulty: 'medium',
+        bug: '`{ ...cfg }` copies the top level only, so `copy.limits` IS `original.limits` and mutating one changes the other.',
+        files: [
+            {
+                path: 'src/clone-config.js',
+                content: `function cloneConfig(config) {
+  return { ...config };
+}
+
+module.exports = { cloneConfig };
+`,
+            },
+            { path: 'test/clone-config.test.js', content: CLONE_CONFIG_TEST },
+        ],
+        fixedFiles: [
+            {
+                path: 'src/clone-config.js',
+                content: `function cloneConfig(config) {
+  return structuredClone(config);
+}
+
+module.exports = { cloneConfig };
+`,
+            },
+        ],
+        target: 'src/clone-config.js',
+        checks: [{ file: 'test/clone-config.test.js', command: 'node test/clone-config.test.js' }],
+        detectionSignals: ['shallow', 'deep', 'nested', 'aliasing', 'reference'],
+        tokenBudget: 20_000,
+    },
+    {
+        id: 'seed-add-tag-mutates-input',
+        title: 'Helper mutates its caller array',
+        axis: 'mutation',
+        difficulty: 'easy',
+        bug: '`tags.push(tag); return tags;` returns the caller\'s own array after mutating it; it must return a new array.',
+        files: [
+            {
+                path: 'src/add-tag.js',
+                content: `function addTag(tags, tag) {
+  tags.push(tag);
+  return tags;
+}
+
+module.exports = { addTag };
+`,
+            },
+            { path: 'test/add-tag.test.js', content: ADD_TAG_TEST },
+        ],
+        fixedFiles: [
+            {
+                path: 'src/add-tag.js',
+                content: `function addTag(tags, tag) {
+  return [...tags, tag];
+}
+
+module.exports = { addTag };
+`,
+            },
+        ],
+        target: 'src/add-tag.js',
+        checks: [{ file: 'test/add-tag.test.js', command: 'node test/add-tag.test.js' }],
+        detectionSignals: ['mutat', 'in place', 'copy', 'push'],
+        tokenBudget: 20_000,
+    },
+    {
+        id: 'seed-average-filtered-denominator',
+        title: 'Denominator not updated with the filter',
+        axis: 'aggregation',
+        difficulty: 'medium',
+        bug: 'Entries are filtered out of the SUM but not out of the DIVISOR, so a missing measurement drags every average down.',
+        files: [
+            {
+                path: 'src/average-of.js',
+                content: `function averageOf(measurements) {
+  const real = measurements.filter((m) => m !== null);
+  if (measurements.length === 0) return 0;
+  const sum = real.reduce((total, value) => total + value, 0);
+  return sum / measurements.length;
+}
+
+module.exports = { averageOf };
+`,
+            },
+            { path: 'test/average-of.test.js', content: AVERAGE_TEST },
+        ],
+        fixedFiles: [
+            {
+                path: 'src/average-of.js',
+                content: `function averageOf(measurements) {
+  const real = measurements.filter((m) => m !== null);
+  if (real.length === 0) return 0;
+  const sum = real.reduce((total, value) => total + value, 0);
+  return sum / real.length;
+}
+
+module.exports = { averageOf };
+`,
+            },
+        ],
+        target: 'src/average-of.js',
+        checks: [{ file: 'test/average-of.test.js', command: 'node test/average-of.test.js' }],
+        detectionSignals: ['denominator', 'divisor', 'length', 'filtered'],
+        tokenBudget: 20_000,
+    },
+];
+/** A bug by id, or undefined. */
+export function seededBugById(id) {
+    return SEEDED_BUGS.find((bug) => bug.id === id);
+}
+/** Write a workspace to `dir`. `fixed` swaps in the reference fix. */
+export function materializeSeededBug(bug, dir, fixed = false) {
+    const files = fixed
+        ? [
+            ...bug.files.filter((f) => !bug.fixedFiles.some((fixedFile) => fixedFile.path === f.path)),
+            ...bug.fixedFiles,
+        ]
+        : bug.files;
+    for (const file of files) {
+        const abs = join(dir, file.path);
+        mkdirSync(join(abs, '..'), { recursive: true });
+        writeFileSync(abs, file.content, 'utf-8');
+    }
+    return dir;
+}
+/** Run one check in a workspace. Never throws — a failure IS the result. */
+export function runSeedCheck(workspace, check, timeoutMs = 30_000) {
+    const start = Date.now();
+    try {
+        const output = execSync(check.command, {
+            cwd: workspace,
+            timeout: timeoutMs,
+            stdio: 'pipe',
+            encoding: 'utf-8',
+            shell: process.platform === 'win32' ? 'cmd.exe' : '/bin/bash',
+            maxBuffer: 2 * 1024 * 1024,
+        });
+        return { command: check.command, exitCode: 0, output: String(output).trim(), durationMs: Date.now() - start };
+    }
+    catch (err) {
+        const e = err;
+        const stdout = typeof e.stdout === 'string' ? e.stdout : String(e.stdout || '');
+        const stderr = typeof e.stderr === 'string' ? e.stderr : String(e.stderr || '');
+        return {
+            command: check.command,
+            // A killed check (timeout) reports no status; 1 keeps it a failure rather
+            // than an accidental pass.
+            exitCode: e.status ?? 1,
+            output: `${stdout}\n${stderr}`.trim(),
+            durationMs: Date.now() - start,
+        };
+    }
+}
+/**
+ * Prove a seed is genuinely broken and genuinely fixable.
+ *
+ * Both halves are required, and the marker requirement is what stops a check that
+ * merely CRASHED from counting as evidence of a bug: a syntax error also exits
+ * non-zero, so "it failed" alone would verify nothing. The fix half is what proves
+ * the check is well-formed; the marker half is what proves the failure is the
+ * defect's.
+ */
+export function verifySeededBug(bug) {
+    const seedDir = mkdtempSync(join(tmpdir(), `seed-verify-${bug.id}-`));
+    const fixedDir = mkdtempSync(join(tmpdir(), `seed-verify-fixed-${bug.id}-`));
+    try {
+        materializeSeededBug(bug, seedDir, false);
+        materializeSeededBug(bug, fixedDir, true);
+        const details = [];
+        let seedFails = true;
+        let fixPasses = true;
+        for (const check of bug.checks) {
+            const seeded = runSeedCheck(seedDir, check);
+            // The marker requirement: the check must fail BY ASSERTING, not by crashing.
+            const failedByAsserting = seeded.exitCode !== 0 && /FAIL/.test(seeded.output);
+            if (!failedByAsserting)
+                seedFails = false;
+            details.push(`    seed  ${check.command} → exit ${seeded.exitCode}` +
+                (failedByAsserting ? '' : ` (no FAIL marker — ${firstLine(seeded.output) || 'no output'})`) +
+                `\n          ${firstLine(seeded.output)}`);
+            const repaired = runSeedCheck(fixedDir, check);
+            if (repaired.exitCode !== 0)
+                fixPasses = false;
+            details.push(`    fixed ${check.command} → exit ${repaired.exitCode}` +
+                (repaired.exitCode === 0 ? '' : ` (${firstLine(repaired.output) || 'no output'})`));
+        }
+        return {
+            id: bug.id,
+            title: bug.title,
+            seedFails,
+            fixPasses,
+            ok: seedFails && fixPasses,
+            detail: details.join('\n'),
+        };
+    }
+    finally {
+        rmSync(seedDir, { recursive: true, force: true });
+        rmSync(fixedDir, { recursive: true, force: true });
+    }
+}
+/** The first non-empty line of output, for a one-line report. */
+function firstLine(output) {
+    return (output || '').split('\n').map((l) => l.trim()).find(Boolean) ?? '';
+}
+/** A table of verifications, ready to print. */
+export function formatSeedVerification(results) {
+    const lines = ['Seeded-bug verification (each seed must FAIL its checks, and PASS once fixed):', ''];
+    for (const result of results) {
+        lines.push(`  ${result.ok ? '✅' : '✗ '} ${result.id.padEnd(36)} ${result.title}`);
+        if (!result.ok) {
+            lines.push(`      seed fails: ${result.seedFails ? 'yes' : 'NO'} · fix passes: ${result.fixPasses ? 'yes' : 'NO'}`);
+            lines.push(result.detail);
+        }
+    }
+    const bad = results.filter((r) => !r.ok).length;
+    lines.push('');
+    lines.push(bad === 0
+        ? `✓ all ${results.length} seeded bug(s) verified — every one is genuinely broken, and genuinely fixable.`
+        : `✗ ${bad} of ${results.length} seeded bug(s) did not verify — a task that is not broken scores nothing.`);
+    return lines.join('\n');
+}
+/** Read a file from a workspace, or null. */
+export function readWorkspaceFile(workspace, path) {
+    try {
+        return readFileSync(join(workspace, path), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=seeded-bugs.js.map

package/dist/learning/seeded-bugs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeded-bugs.js","sourceRoot":"","sources":["../../src/learning/seeded-bugs.ts"],"names":[],"mappings":"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"}

package/dist/learning/step-checkpoint.d.ts

@@ -0,0 +1,127 @@
+/**
+ * WS5 (#27) — the resume ledger: replay a run's unchanged MODEL CALLS.
+ *
+ * WHY REPLAYING MODEL CALLS IS THE USEFUL UNIT. `--resume` already existed for the
+ * pipeline engine, where it skips completed TASKS (`agents/checkpoint-store.ts`).
+ * A task is a coarse unit: one that half-finished is re-run from its start, and on
+ * an agent LOOP — where a turn is many model calls, each of which may have cost a
+ * slow provider round trip — the expensive thing is the calls, not the tasks. So
+ * this ledger records each step's answer and replays the ones whose input has not
+ * changed, which is what makes a re-run cost two calls instead of twenty.
+ *
+ * WHY THE KEY IS A DIGEST OF THE WHOLE INPUT, NOT THE STEP NUMBER. A step's number
+ * is the same on every run and means nothing about its content: replay by position
+ * and a plan that shifted by one step serves an answer to a question that was never
+ * asked — silently, because a replayed answer is indistinguishable from a fresh one
+ * in the transcript. The digest covers the whole thread AND the tool schema, so a
+ * changed tool result, a changed schema, a reordered message or an edited goal all
+ * MISS and the step is paid for again.
+ *
+ * WHY AN EMPTY RECORDED STEP IS NEVER REPLAYED. A response with no text and no tool
+ * call is a provider failure, not an answer. Replaying it would reproduce the
+ * failure while removing the only thing that would have fixed it — the call itself
+ * — and would hide the fact that the provider was never consulted.
+ *
+ * WHY NOTHING HAPPENS WITHOUT A REQUEST. An ordinary run must not read, write, or
+ * even look for a record: `--resume` is the only thing that opens the store, and a
+ * turn that was never asked to resume pays no filesystem cost and cannot inherit
+ * another run's answers by accident.
+ *
+ * WHY IT REPORTS WHAT IT LOADED AND WHAT IT REPLAYED SEPARATELY. At open time the
+ * only knowable fact is what the RECORD holds; whether any of it will be usable is
+ * decided step by step, once the thread is actually built. Announcing an outcome at
+ * open is how a resumed run came to print "nothing to replay" before it had tried
+ * anything — including on runs that then replayed everything.
+ */
+import type { ToolCallResponse } from '../inference/interface.js';
+/** The environment key a deployment asks for a resume through. */
+export declare const RESUME_ENABLE_ENV = "NUVIRA_RESUME";
+/** ─── Requests ─────────────────────────────────────────────────────────────── */
+/**
+ * A resolved resume request.
+ *
+ * An absent `id` means "the record for this ask, in this directory" — resolved at
+ * open time through `checkpointIdFor`, which is what makes `--resume` with no
+ * argument mean the LAST run of the same ask HERE, rather than some global newest.
+ */
+export interface ResumeRequest {
+    id?: string;
+}
+/**
+ * Resolve a resume request from a caller's option, with the environment as the
+ * fallback.
+ *
+ * `undefined` means nobody said anything, and only then does `NUVIRA_RESUME`
+ * decide (`1` asks for the auto record, any other value names one). An explicit
+ * `false` is a DECISION and outranks the environment, so a surface with an off
+ * switch can decline a request a deployment made for every turn.
+ */
+export declare function resolveResumeRequest(input: {
+    resume?: string | boolean;
+}): ResumeRequest | undefined;
+/** ─── Digests ──────────────────────────────────────────────────────────────── */
+/**
+ * The key a step is stored under: a hash of its whole input.
+ *
+ * Key ORDER is normalised, so a tool-call argument object that came back with its
+ * keys in a different order hashes the same — that is a JSON-round-trip artefact,
+ * not a change of input — while a different VALUE anywhere hashes differently.
+ */
+export declare function stepDigest(thread: readonly unknown[], schemas: readonly unknown[]): string;
+/** ─── The ledger ───────────────────────────────────────────────────────────── */
+/**
+ * The ledger a loop threads its steps through.
+ *
+ * Deliberately tiny: `replay` answers "was this step already answered, and for
+ * THIS input", `record` files an answer for the next run, and `openNotice` says
+ * what the record held. Everything a caller needs to decide is here; how the
+ * numbers are reported is `closeResume`'s job.
+ */
+export interface StepReplay {
+    /** The recorded answer for this exact input, or null (with a reason recorded). */
+    replay(key: string, digest: string): ToolCallResponse | null;
+    /** File an answer this run paid for, so the next one can replay it. */
+    record(key: string, digest: string, response: ToolCallResponse): void;
+    /** What the RECORD held, said before any step was attempted. */
+    openNotice(): string;
+}
+/** An opened resume: its record id, and the ledger to thread through the run. */
+export interface OpenResume {
+    id: string;
+    goal: string;
+    cwd: string;
+    ledger: StepReplay;
+}
+/**
+ * Open the record for this ask, reading it once (a record is not re-read per step).
+ */
+export declare function openResume(input: {
+    goal: string;
+    cwd: string;
+    resume: ResumeRequest;
+}): OpenResume;
+/** What a resumed run replayed, what it paid for, and whether the record survived. */
+export interface ResumeOutcome {
+    id: string;
+    /** Steps served from the record (each one a model call NOT made). */
+    replayed: number;
+    /** Model calls the RESUMED run still made (0 = every step came from the record). */
+    modelCalls: number;
+    /** False when the record could not be written (the run itself still happened). */
+    saved: boolean;
+    /** The operator-facing line: the counts, and why nothing replayed when it didn't. */
+    notice: string;
+}
+/**
+ * Close the ledger: write back what this run learned, and report the real counts.
+ *
+ * The record is rewritten only from what this run staged — the entries it replayed
+ * plus the ones it paid for — which is what makes the chain work: the next resume
+ * replays what this one learned, and a step nobody could use is not carried along
+ * as if it had been.
+ */
+export declare function closeResume(resume: OpenResume, input: {
+    goal: string;
+    cwd: string;
+}): ResumeOutcome;
+//# sourceMappingURL=step-checkpoint.d.ts.map