@esankhan3/anvil-agent-core 0.1.0

package/dist/checkpoint/store.d.ts

@@ -0,0 +1,91 @@
+/**
+ * CheckpointStore — persistence for CheckpointRecord JSON files.
+ *
+ * Storage layout:
+ *   <anvilHome>/checkpoints/<project>/<runFamily>/<stage>/<hash>.json
+ *   <anvilHome>/checkpoints/_blobs/<sha[0:2]>/<sha>      (via BlobStore)
+ *
+ * All writes go through tmp + renameSync for atomicity. Missing or corrupt
+ * JSON files are treated as absent (get returns null and logs to stderr).
+ *
+ * ── Stats accounting (approximate) ───────────────────────────────────────
+ *
+ * `stats()` mixes two data sources:
+ *   - On-disk counts (total/completed/interrupted/failed) are authoritative.
+ *   - `hits` is an in-memory counter incremented inside `get()` every time a
+ *     caller observes a `completed` record. `misses` counts `begin()` calls.
+ *
+ * This means `hits` resets across process restarts — it reflects *this*
+ * process's cache-reuse activity, not lifetime reuse. `hitRate` is computed
+ * as hits / (hits + misses). The costSavedUsd estimate sums the cost of
+ * each observed hit (i.e. the cost Anvil would have paid to re-run it).
+ * Misses before a restart are not retroactively credited.
+ *
+ * This approximation is documented here and referenced by the integration
+ * notes. It's intentional: we don't need a durable hit counter for the
+ * main goal (skip already-done work); the metric is informational.
+ */
+import { BlobStore } from './blob-store.js';
+import type { CheckpointInputs, CheckpointKey, CheckpointRecord, CheckpointStage, CheckpointStats, CheckpointStatus } from './types.js';
+export interface CheckpointStoreOpts {
+    anvilHome: string;
+    blobStore: BlobStore;
+}
+export declare class CheckpointStore {
+    private readonly anvilHome;
+    private readonly blobStore;
+    /** In-memory hit/miss counters; see file header for semantics. */
+    private hitCount;
+    private missCount;
+    private hitCostUsd;
+    constructor(opts: CheckpointStoreOpts);
+    /**
+     * Look up a checkpoint by key. Returns null when missing or corrupt. If the
+     * returned record is `completed` and its blob exists, increments the hit
+     * counter (and adds its recorded cost to costSavedUsd).
+     */
+    get(project: string, runFamily: string, key: CheckpointKey): CheckpointRecord | null;
+    /** Persist a record to disk atomically. */
+    write(project: string, record: CheckpointRecord): void;
+    /**
+     * Claim a checkpoint: write `status: 'running'` with startedAt. Used
+     * before the agent executes so interrupted runs can be detected on
+     * resume. Counts as a cache miss.
+     */
+    begin(project: string, runFamily: string, inputs: CheckpointInputs, cost?: CheckpointRecord['cost']): CheckpointRecord;
+    /**
+     * Mark a checkpoint completed with its serialized output. Writes the blob
+     * first (so a subsequent `get` that sees the record always finds bytes).
+     */
+    complete(project: string, runFamily: string, key: CheckpointKey, output: string | Buffer, cost?: CheckpointRecord['cost']): CheckpointRecord;
+    /**
+     * Mark a checkpoint as interrupted (SIGTERM / cost-reject / user cancel).
+     * If a partial output is provided, it is stored as a blob so the next
+     * resume can inspect it.
+     */
+    interrupt(project: string, runFamily: string, key: CheckpointKey, partialOutput?: string | Buffer, reason?: string): CheckpointRecord;
+    /** Mark a checkpoint as failed with the error message. */
+    fail(project: string, runFamily: string, key: CheckpointKey, err: string): CheckpointRecord;
+    /**
+     * Enumerate every checkpoint record for a given run family across all
+     * stages. Skips corrupt files silently.
+     */
+    listForRun(project: string, runFamily: string): CheckpointRecord[];
+    /**
+     * Delete on-disk records for a stage within a run. Does NOT touch blobs
+     * (those are content-addressed; use `BlobStore.gc` for that).
+     */
+    invalidateStage(project: string, runFamily: string, stage: CheckpointStage): number;
+    /** Aggregate stats for a run family. See file header for approximation notes. */
+    stats(project: string, runFamily: string): CheckpointStats;
+    /** Visible for tests: reset in-memory hit/miss accounting. */
+    resetCounters(): void;
+    /** Visible for tests: current in-memory counters. */
+    getCounters(): {
+        hits: number;
+        misses: number;
+        hitCostUsd: number;
+    };
+}
+export type { CheckpointStatus };
+//# sourceMappingURL=store.d.ts.map

package/dist/checkpoint/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/checkpoint/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AA2CpB,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAK;gBAEX,IAAI,EAAE,mBAAmB;IAKrC;;;;OAIG;IACH,GAAG,CACD,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,aAAa,GACjB,gBAAgB,GAAG,IAAI;IAqB1B,2CAA2C;IAC3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAWtD;;;;OAIG;IACH,KAAK,CACH,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAC9B,gBAAgB;IAcnB;;;OAGG;IACH,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAC9B,gBAAgB;IA2BnB;;;;OAIG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,aAAa,EAClB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,gBAAgB;IA+BnB,0DAA0D;IAC1D,IAAI,CACF,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,gBAAgB;IA0BnB;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE;IA4BlE;;;OAGG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,GACrB,MAAM;IA2BT,iFAAiF;IACjF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe;IAkB1D,8DAA8D;IAC9D,aAAa,IAAI,IAAI;IAMrB,qDAAqD;IACrD,WAAW,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;CAGpE;AAED,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/checkpoint/store.js

@@ -0,0 +1,292 @@
+/**
+ * CheckpointStore — persistence for CheckpointRecord JSON files.
+ *
+ * Storage layout:
+ *   <anvilHome>/checkpoints/<project>/<runFamily>/<stage>/<hash>.json
+ *   <anvilHome>/checkpoints/_blobs/<sha[0:2]>/<sha>      (via BlobStore)
+ *
+ * All writes go through tmp + renameSync for atomicity. Missing or corrupt
+ * JSON files are treated as absent (get returns null and logs to stderr).
+ *
+ * ── Stats accounting (approximate) ───────────────────────────────────────
+ *
+ * `stats()` mixes two data sources:
+ *   - On-disk counts (total/completed/interrupted/failed) are authoritative.
+ *   - `hits` is an in-memory counter incremented inside `get()` every time a
+ *     caller observes a `completed` record. `misses` counts `begin()` calls.
+ *
+ * This means `hits` resets across process restarts — it reflects *this*
+ * process's cache-reuse activity, not lifetime reuse. `hitRate` is computed
+ * as hits / (hits + misses). The costSavedUsd estimate sums the cost of
+ * each observed hit (i.e. the cost Anvil would have paid to re-run it).
+ * Misses before a restart are not retroactively credited.
+ *
+ * This approximation is documented here and referenced by the integration
+ * notes. It's intentional: we don't need a durable hit counter for the
+ * main goal (skip already-done work); the metric is informational.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { checkpointPath, checkpointRoot, computeKey } from './key.js';
+const STAGES = [
+    'plan',
+    'implement',
+    'review',
+    'test',
+    'ship',
+    'kb-grounding',
+    'mutation',
+];
+function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+function atomicWriteFileSync(filePath, data) {
+    ensureDir(dirname(filePath));
+    const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        writeFileSync(tmp, data, 'utf-8');
+        renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+function readRecord(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        process.stderr.write(`[checkpoint-store] skipping corrupt record ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+export class CheckpointStore {
+    anvilHome;
+    blobStore;
+    /** In-memory hit/miss counters; see file header for semantics. */
+    hitCount = 0;
+    missCount = 0;
+    hitCostUsd = 0;
+    constructor(opts) {
+        this.anvilHome = opts.anvilHome;
+        this.blobStore = opts.blobStore;
+    }
+    /**
+     * Look up a checkpoint by key. Returns null when missing or corrupt. If the
+     * returned record is `completed` and its blob exists, increments the hit
+     * counter (and adds its recorded cost to costSavedUsd).
+     */
+    get(project, runFamily, key) {
+        const path = checkpointPath(this.anvilHome, project, runFamily, key.stage, key.hash);
+        const record = readRecord(path);
+        if (!record)
+            return null;
+        if (record.status === 'completed' &&
+            record.outputRef &&
+            this.blobStore.exists(record.outputRef)) {
+            this.hitCount += 1;
+            if (record.cost?.usd)
+                this.hitCostUsd += record.cost.usd;
+        }
+        return record;
+    }
+    /** Persist a record to disk atomically. */
+    write(project, record) {
+        const path = checkpointPath(this.anvilHome, project, record.key.runFamily, record.key.stage, record.key.hash);
+        atomicWriteFileSync(path, JSON.stringify(record, null, 2));
+    }
+    /**
+     * Claim a checkpoint: write `status: 'running'` with startedAt. Used
+     * before the agent executes so interrupted runs can be detected on
+     * resume. Counts as a cache miss.
+     */
+    begin(project, runFamily, inputs, cost) {
+        const key = computeKey(runFamily, inputs);
+        const record = {
+            key,
+            project,
+            status: 'running',
+            startedAt: new Date().toISOString(),
+            ...(cost ? { cost } : {}),
+        };
+        this.write(project, record);
+        this.missCount += 1;
+        return record;
+    }
+    /**
+     * Mark a checkpoint completed with its serialized output. Writes the blob
+     * first (so a subsequent `get` that sees the record always finds bytes).
+     */
+    complete(project, runFamily, key, output, cost) {
+        const blob = this.blobStore.write(output);
+        const path = checkpointPath(this.anvilHome, project, runFamily, key.stage, key.hash);
+        const existing = readRecord(path);
+        const startedAt = existing?.startedAt ?? new Date().toISOString();
+        const completedAt = new Date().toISOString();
+        const durationMs = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+        const record = {
+            key,
+            project,
+            status: 'completed',
+            outputRef: blob.sha,
+            startedAt,
+            completedAt,
+            durationMs,
+            ...(cost ? { cost } : existing?.cost ? { cost: existing.cost } : {}),
+        };
+        this.write(project, record);
+        return record;
+    }
+    /**
+     * Mark a checkpoint as interrupted (SIGTERM / cost-reject / user cancel).
+     * If a partial output is provided, it is stored as a blob so the next
+     * resume can inspect it.
+     */
+    interrupt(project, runFamily, key, partialOutput, reason) {
+        const path = checkpointPath(this.anvilHome, project, runFamily, key.stage, key.hash);
+        const existing = readRecord(path);
+        const startedAt = existing?.startedAt ?? new Date().toISOString();
+        const completedAt = new Date().toISOString();
+        const durationMs = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+        let outputRef;
+        if (partialOutput !== undefined) {
+            outputRef = this.blobStore.write(partialOutput).sha;
+        }
+        const record = {
+            key,
+            project,
+            status: 'interrupted',
+            startedAt,
+            completedAt,
+            durationMs,
+            ...(outputRef ? { outputRef } : {}),
+            ...(reason ? { errorMessage: reason } : {}),
+            ...(existing?.cost ? { cost: existing.cost } : {}),
+        };
+        this.write(project, record);
+        return record;
+    }
+    /** Mark a checkpoint as failed with the error message. */
+    fail(project, runFamily, key, err) {
+        const path = checkpointPath(this.anvilHome, project, runFamily, key.stage, key.hash);
+        const existing = readRecord(path);
+        const startedAt = existing?.startedAt ?? new Date().toISOString();
+        const completedAt = new Date().toISOString();
+        const durationMs = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+        const record = {
+            key,
+            project,
+            status: 'failed',
+            startedAt,
+            completedAt,
+            durationMs,
+            errorMessage: err,
+            ...(existing?.cost ? { cost: existing.cost } : {}),
+        };
+        this.write(project, record);
+        return record;
+    }
+    /**
+     * Enumerate every checkpoint record for a given run family across all
+     * stages. Skips corrupt files silently.
+     */
+    listForRun(project, runFamily) {
+        const runDir = join(checkpointRoot(this.anvilHome), project, runFamily);
+        if (!existsSync(runDir))
+            return [];
+        const out = [];
+        let stageDirs;
+        try {
+            stageDirs = readdirSync(runDir);
+        }
+        catch {
+            return [];
+        }
+        for (const stage of stageDirs) {
+            if (!STAGES.includes(stage))
+                continue;
+            const stageDir = join(runDir, stage);
+            let files;
+            try {
+                files = readdirSync(stageDir);
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const rec = readRecord(join(stageDir, file));
+                if (rec)
+                    out.push(rec);
+            }
+        }
+        return out;
+    }
+    /**
+     * Delete on-disk records for a stage within a run. Does NOT touch blobs
+     * (those are content-addressed; use `BlobStore.gc` for that).
+     */
+    invalidateStage(project, runFamily, stage) {
+        const stageDir = join(checkpointRoot(this.anvilHome), project, runFamily, stage);
+        if (!existsSync(stageDir))
+            return 0;
+        let count = 0;
+        let files;
+        try {
+            files = readdirSync(stageDir);
+        }
+        catch {
+            return 0;
+        }
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                unlinkSync(join(stageDir, file));
+                count += 1;
+            }
+            catch {
+                // best effort
+            }
+        }
+        return count;
+    }
+    /** Aggregate stats for a run family. See file header for approximation notes. */
+    stats(project, runFamily) {
+        const records = this.listForRun(project, runFamily);
+        const total = records.length;
+        const interrupted = records.filter((r) => r.status === 'interrupted').length;
+        const hits = this.hitCount;
+        const misses = this.missCount;
+        const denom = hits + misses;
+        const hitRate = denom === 0 ? 0 : hits / denom;
+        return {
+            total,
+            hits,
+            misses,
+            interrupted,
+            hitRate,
+            costSavedUsd: this.hitCostUsd,
+        };
+    }
+    /** Visible for tests: reset in-memory hit/miss accounting. */
+    resetCounters() {
+        this.hitCount = 0;
+        this.missCount = 0;
+        this.hitCostUsd = 0;
+    }
+    /** Visible for tests: current in-memory counters. */
+    getCounters() {
+        return { hits: this.hitCount, misses: this.missCount, hitCostUsd: this.hitCostUsd };
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/checkpoint/store.js.map

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

package/dist/checkpoint/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Phase 9 — Deterministic agent checkpoints.
+ *
+ * Types shared across the checkpoint subsystem: the key/fingerprint
+ * computation (`checkpoint-key.ts`), the content-addressed blob store
+ * (`checkpoint-blob-store.ts`), the record store (`checkpoint-store.ts`),
+ * and the higher-order agent wrapper (`agent-runner-wrapper.ts`).
+ *
+ * A checkpoint is a per-(project, runFamily, stage, hash) record of whether
+ * a particular agent invocation has already produced output, so that a
+ * resumed run can skip it. The hash is a sha256 derived from a stable
+ * fingerprint of every input that should invalidate the cache on drift
+ * (prompt version, tool versions, model id, and the input payload).
+ */
+/** Logical pipeline stages that emit checkpoints. */
+export type CheckpointStage = 'plan' | 'implement' | 'review' | 'test' | 'ship' | 'kb-grounding' | 'mutation';
+/** Lifecycle state of a single checkpoint record. */
+export type CheckpointStatus = 'pending' | 'running' | 'completed' | 'interrupted' | 'failed';
+/**
+ * The inputs that go into computing a checkpoint key.
+ *
+ * Any field here drifts → different hash → cache miss → fresh run. Fields
+ * are intentionally denormalized so callers don't forget to include
+ * promptVersion / model etc.
+ */
+export interface CheckpointInputs {
+    stage: CheckpointStage;
+    /** Stable task identifier within a stage (e.g. "impl:src/foo.ts"). */
+    taskId: string;
+    /** Arbitrary JSON-serializable input payload; fingerprinted recursively. */
+    inputs: unknown;
+    /** Persona / prompt version string — bump to invalidate cached outputs. */
+    promptVersion: string;
+    /** Tool versions that materially affect output (e.g. { tsc: '5.3.3' }). */
+    toolVersions?: Record<string, string>;
+    /** Model identifier used for the invocation. */
+    model?: string;
+}
+/** Identifier for a checkpoint, computed from CheckpointInputs. */
+export interface CheckpointKey {
+    /** sha256 hex string uniquely identifying the input set. */
+    hash: string;
+    /** Groups re-runs of the same logical run across retries / resumes. */
+    runFamily: string;
+    stage: CheckpointStage;
+    taskId: string;
+}
+/** On-disk record for one checkpoint. */
+export interface CheckpointRecord {
+    key: CheckpointKey;
+    project: string;
+    status: CheckpointStatus;
+    /** Content-addressed blob sha (hex) for the serialized output. */
+    outputRef?: string;
+    cost?: {
+        usd: number;
+        tokensIn: number;
+        tokensOut: number;
+    };
+    startedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    errorMessage?: string;
+}
+/** Aggregate metrics for a run family. */
+export interface CheckpointStats {
+    total: number;
+    hits: number;
+    misses: number;
+    interrupted: number;
+    hitRate: number;
+    costSavedUsd: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/checkpoint/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/checkpoint/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qDAAqD;AACrD,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,WAAW,GACX,QAAQ,GACR,MAAM,GACN,MAAM,GACN,cAAc,GACd,UAAU,CAAC;AAEf,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,WAAW,GACX,aAAa,GACb,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,eAAe,CAAC;IACvB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,aAAa,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,gBAAgB,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/checkpoint/types.js

@@ -0,0 +1,16 @@
+/**
+ * Phase 9 — Deterministic agent checkpoints.
+ *
+ * Types shared across the checkpoint subsystem: the key/fingerprint
+ * computation (`checkpoint-key.ts`), the content-addressed blob store
+ * (`checkpoint-blob-store.ts`), the record store (`checkpoint-store.ts`),
+ * and the higher-order agent wrapper (`agent-runner-wrapper.ts`).
+ *
+ * A checkpoint is a per-(project, runFamily, stage, hash) record of whether
+ * a particular agent invocation has already produced output, so that a
+ * resumed run can skip it. The hash is a sha256 derived from a stable
+ * fingerprint of every input that should invalidate the cache on drift
+ * (prompt version, tool versions, model id, and the input payload).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/checkpoint/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/checkpoint/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/claude-adapter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Claude CLI ModelAdapter.
+ *
+ * The simplest adapter — Claude CLI already outputs Anvil Stream Format
+ * natively (`--output-format stream-json`), so we just pipe stdout through
+ * with zero transformation.
+ */
+import type { ModelAdapter, ModelAdapterConfig, ModelAdapterResult, ProviderCapabilities, ProviderName } from './types.js';
+export declare class ClaudeAdapter implements ModelAdapter {
+    readonly provider: ProviderName;
+    readonly capabilities: ProviderCapabilities;
+    private child;
+    supportsModel(modelId: string): boolean;
+    getModelPricing(modelId: string): [number, number] | null;
+    checkAvailability(): Promise<{
+        available: boolean;
+        version?: string;
+        error?: string;
+    }>;
+    run(config: ModelAdapterConfig, output: NodeJS.WritableStream): Promise<ModelAdapterResult>;
+    kill(): void;
+}
+//# sourceMappingURL=claude-adapter.d.ts.map

package/dist/claude-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-adapter.d.ts","sourceRoot":"","sources":["../src/claude-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACb,MAAM,YAAY,CAAC;AAuCpB,qBAAa,aAAc,YAAW,YAAY;IAChD,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAY;IAE3C,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAczC;IAEF,OAAO,CAAC,KAAK,CAA6B;IAE1C,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAUvC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAKnD,iBAAiB,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAUtF,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA+JjG,IAAI,IAAI,IAAI;CAMb"}