@arnilo/prism 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export type { CacheTelemetry, CacheTelemetryOptions, CacheTelemetryReport, Cache
 export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, createCacheTelemetry, DEFAULT_CACHE_TELEMETRY_CAP, } from "./cache-telemetry.js";
 export type { ProviderCapture, ProviderCaptureEntry, ProviderCaptureOptions, ProviderCapturePolicy } from "./capture.js";
 export { createProviderCapture } from "./capture.js";
-export type { CheckpointRestoreAudit, CheckpointRestoreAuditEntry, CheckpointRestoreHook, RunCheckpointRestoreHooksOptions, } from "./checkpoint-restore.js";
+export type { CheckpointRestoreAudit, CheckpointRestoreAuditEntry, CheckpointRestoreCompensation, CheckpointRestoreHandler, CheckpointRestoreHook, RunCheckpointRestoreHooksOptions, } from "./checkpoint-restore.js";
 export { CheckpointRestoreError, DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS, runCheckpointRestoreHooks } from "./checkpoint-restore.js";
 export type { MemoryCheckpointStoreOptions } from "./checkpoints.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
@@ -96,7 +96,7 @@ export type { RunBundleSnapshot, RunBundleSnapshotInput } from "./run-bundle.js"
 export { RUN_BUNDLE_SCHEMA_VERSION, snapshotRunBundle } from "./run-bundle.js";
 export type { BatchedRunLedgerOptions } from "./run-ledger.js";
 export { createBatchedRunLedger, DEFAULT_LEDGER_BATCH_BYTES, DEFAULT_LEDGER_BATCH_DELAY_MS, DEFAULT_LEDGER_BATCH_ENTRIES, HARD_LEDGER_BATCH_BYTES, HARD_LEDGER_BATCH_DELAY_MS, HARD_LEDGER_BATCH_ENTRIES, isFlushableRunLedger, } from "./run-ledger.js";
-export type { RunLimitTrackerOptions } from "./run-limits.js";
+export type { BudgetExhaustionAttribution, RunLimitTrackerOptions } from "./run-limits.js";
 export { createRunLimitTracker, DEFAULT_RUN_LIMITS, HARD_RUN_LIMITS, RunLimitError, RunLimitTracker, resolveRunLimits, } from "./run-limits.js";
 export type { HostCompositionGovernance, HostCompositionOptions, HostCompositionProfile, HostCompositionReport, HostCompositionToolReport, } from "./secure-agent.js";
 export { assertHostCompositionReadiness, createSecureAgent, HostCompositionError, inspectHostComposition, } from "./secure-agent.js";
@@ -131,5 +131,5 @@ export { MODEL_FAMILY_TOKENS, resolveModelFamily } from "./usage-estimation.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.10.0";
+export declare const version = "0.11.0";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -72,6 +72,6 @@ export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { MODEL_FAMILY_TOKENS, resolveModelFamily } from "./usage-estimation.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.10.0";
+export const version = "0.11.0";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/leases.js

@@ -6,10 +6,24 @@ export class LeaseConflictError extends Error {
         this.name = "LeaseConflictError";
     }
 }
+/** Drop expired rows once the map reaches this size. Live rows are never evicted. */
+const EXPIRED_LEASE_SWEEP_AT = 1_024;
+/** Test-only size probe. Not a LeaseStore field. */
+const LEASE_RECORD_COUNT = Symbol.for("prism.lease.recordCount");
 /** In-process reference implementation. Durable adapters provide cross-process exclusion. */
 export function createMemoryLeaseStore() {
     const records = new Map();
-    return {
+    // ponytail: full scan only at EXPIRED_LEASE_SWEEP_AT, so a write is O(1) until then.
+    // Live leases are unbounded. Upgrade: cap live rows if a host holds more than the threshold.
+    function sweepExpired(now) {
+        if (records.size < EXPIRED_LEASE_SWEEP_AT)
+            return;
+        for (const [id, record] of records) {
+            if (Date.parse(record.expiresAt) <= now)
+                records.delete(id);
+        }
+    }
+    const store = {
         async tryAcquireLease(input) {
             validateAcquire(input);
             const id = keyOf(input);
@@ -17,7 +31,9 @@ export function createMemoryLeaseStore() {
             if (current)
                 assertOwnership(input, current);
             const now = Date.now();
-            if (current && Date.parse(current.expiresAt) > now)
+            sweepExpired(now);
+            const held = records.get(id);
+            if (held && Date.parse(held.expiresAt) > now)
                 return null;
             const timestamp = new Date(now).toISOString();
             const record = {
@@ -25,7 +41,7 @@ export function createMemoryLeaseStore() {
                 key: input.key,
                 ownerId: input.ownerId,
                 token: crypto.randomUUID(),
-                fencingToken: (current?.fencingToken ?? 0) + 1,
+                fencingToken: (held?.fencingToken ?? 0) + 1,
                 acquiredAt: timestamp,
                 expiresAt: new Date(now + input.ttlMs).toISOString(),
                 updatedAt: timestamp,
@@ -37,30 +53,38 @@ export function createMemoryLeaseStore() {
         async renewLease(input) {
             validateClaim(input, true);
             const current = records.get(keyOf(input));
-            if (!current)
+            if (!current) {
+                sweepExpired(Date.now());
                 return null;
+            }
             assertOwnership(input, current);
             const now = Date.now();
-            if (current.ownerId !== input.ownerId || current.token !== input.token || Date.parse(current.expiresAt) <= now)
+            if (current.ownerId !== input.ownerId || current.token !== input.token || Date.parse(current.expiresAt) <= now) {
+                sweepExpired(now);
                 return null;
+            }
             const record = {
                 ...current,
                 expiresAt: new Date(now + input.ttlMs).toISOString(),
                 updatedAt: new Date(now).toISOString(),
             };
             records.set(keyOf(input), record);
+            sweepExpired(now);
             return record;
         },
         async releaseLease(input) {
             validateClaim(input, false);
             const current = records.get(keyOf(input));
-            if (!current)
+            if (!current) {
+                sweepExpired(Date.now());
                 return false;
+            }
             assertOwnership(input, current);
             if (current.ownerId !== input.ownerId || current.token !== input.token)
                 return false;
             const now = new Date().toISOString();
             records.set(keyOf(input), { ...current, expiresAt: now, updatedAt: now });
+            sweepExpired(Date.now());
             return true;
         },
         async getLease(input) {
@@ -72,6 +96,8 @@ export function createMemoryLeaseStore() {
             return Date.parse(current.expiresAt) > Date.now() ? current : null;
         },
     };
+    Object.defineProperty(store, LEASE_RECORD_COUNT, { get: () => records.size });
+    return store;
 }
 function keyOf(input) {
     return `${input.namespace}\0${input.key}`;

package/dist/node/contribution-discovery.d.ts

@@ -1,4 +1,4 @@
-import type { ContributionFileKind, DiscoveredContribution } from "../contracts.js";
+import type { ContributionFileKind, DiscoveredContribution, Skill } from "../contracts.js";
 import type { PermissionPolicy, TrustPolicy } from "../security.js";
 export interface DiscoveryOptions {
     readonly kinds: readonly ContributionFileKind[];
@@ -14,3 +14,18 @@ export interface DiscoveryOptions {
  */
 export declare function discoverContributions(options: DiscoveryOptions): Promise<readonly DiscoveredContribution[]>;
 export declare function readOptionalFile(path: string): Promise<string | undefined>;
+export interface LoadSkillDirectoryOptions {
+    /** Per-file byte cap; defaults to `HARD_MAX_SKILL_INSTRUCTION_BYTES` (262 144). */
+    readonly maxSkillBytes?: number;
+}
+/**
+ * Load a host-supplied `<directory>/<name>/SKILL.md` tree (an upstream persona
+ * or provider checkout) into inert {@link Skill} values. Bounded per file,
+ * symlink-contained, and deterministic (sorted by directory name); nothing is
+ * auto-activated — the host registers the result through `api.registerSkill` or
+ * its own loader.
+ *
+ * Throws when `directory` is unreadable or a SKILL.md exceeds the cap. A
+ * subdirectory without SKILL.md (or a symlink escaping `directory`) is skipped.
+ */
+export declare function loadSkillDirectory(directory: string, options?: LoadSkillDirectoryOptions): Promise<readonly Skill[]>;

package/dist/node/contribution-discovery.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { isJsonObject } from "../config.js";
 import { parseSkillFile } from "../contribution-parsing.js";
 import { assertPermission } from "../security.js";
+import { HARD_MAX_SKILL_INSTRUCTION_BYTES } from "../skill-disclosure.js";
 import { isNodeErrorCode } from "./config.js";
 import { isPathInsideReal } from "./trust.js";
 /**
@@ -103,6 +104,52 @@ export async function readOptionalFile(path) {
         throw error;
     }
 }
+/**
+ * Load a host-supplied `<directory>/<name>/SKILL.md` tree (an upstream persona
+ * or provider checkout) into inert {@link Skill} values. Bounded per file,
+ * symlink-contained, and deterministic (sorted by directory name); nothing is
+ * auto-activated — the host registers the result through `api.registerSkill` or
+ * its own loader.
+ *
+ * Throws when `directory` is unreadable or a SKILL.md exceeds the cap. A
+ * subdirectory without SKILL.md (or a symlink escaping `directory`) is skipped.
+ */
+export async function loadSkillDirectory(directory, options = {}) {
+    const maxBytes = options.maxSkillBytes ?? HARD_MAX_SKILL_INSTRUCTION_BYTES;
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        throw new Error(`No readable skill directory at ${directory}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const skills = [];
+    for (const name of [...names].sort()) {
+        const dir = join(directory, name);
+        let isDir;
+        try {
+            isDir = (await stat(dir)).isDirectory();
+        }
+        catch (error) {
+            if (isNodeErrorCode(error, "ENOENT"))
+                continue;
+            throw error;
+        }
+        if (!isDir || !(await isPathInsideReal(directory, dir)))
+            continue;
+        const path = join(dir, "SKILL.md");
+        if (!(await isPathInsideReal(directory, path)))
+            continue;
+        const text = await readOptionalFile(path);
+        if (text === undefined)
+            continue;
+        if (Buffer.byteLength(text, "utf8") > maxBytes) {
+            throw new Error(`Skill file ${path} exceeds ${maxBytes} byte cap`);
+        }
+        skills.push(parseSkillFile(text, path));
+    }
+    return skills;
+}
 // --- Internal helpers. ---
 // ponytail: parseSkillFile/parseAgentFile live in ../contribution-parsing.ts (core, fs-free); this
 // Node module owns directory walking + manifest.json parsing only.

package/dist/node/session-store-jsonl.js

@@ -1,8 +1,19 @@
-import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 import { isSessionEntryKind, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_SCHEMA_VERSION, SessionAppendConflictError, } from "../contracts.js";
 import { searchLinearSessions } from "../session-stores.js";
 import { isNodeErrorCode } from "./config.js";
+const IDEMPOTENCY_SEEN_MAX = 4_096;
+function rememberIdempotencyKey(seen, key) {
+    if (seen.size >= IDEMPOTENCY_SEEN_MAX) {
+        const oldest = seen.values().next().value;
+        if (oldest !== undefined)
+            seen.delete(oldest);
+    }
+    seen.add(key);
+}
+/** Test-only read counter on the store instance. Not a SessionStore field. */
+const JSONL_FILE_READS = Symbol.for("prism.jsonl.fileReads");
 export function createJsonlSessionStore(pathOrOptions) {
     const options = typeof pathOrOptions === "string" ? { path: pathOrOptions, createDirectory: true } : pathOrOptions;
     const path = options.path;
@@ -13,14 +24,50 @@ export function createJsonlSessionStore(pathOrOptions) {
     // lock). The expectedParentId/idempotency guards below mirror the memory store;
     // a DB adapter enforces them via a conditional transaction + unique index.
     const idempotencySeen = new Set();
-    return {
+    // ponytail: cache key is (size, mtimeMs). A same-size rewrite inside one filesystem
+    // timestamp tick is invisible. Upgrade: hash the file. Post-write size !== prior
+    // size + bytes written already drops the cache so the next read re-parses.
+    let cache;
+    let fileReads = 0;
+    async function readParsed() {
+        fileReads++;
+        return readJsonlSessionEntries(path);
+    }
+    async function readEntries() {
+        let st;
+        try {
+            const info = await stat(path);
+            st = { size: info.size, mtimeMs: info.mtimeMs };
+        }
+        catch (error) {
+            if (isNodeErrorCode(error, "ENOENT")) {
+                cache = undefined;
+                return [];
+            }
+            throw new Error(`Failed to read session store ${path}: ${errorMessage(error)}`);
+        }
+        if (cache && cache.size === st.size && cache.mtimeMs === st.mtimeMs)
+            return cache.entries;
+        const result = await readParsed();
+        cache = { size: st.size, mtimeMs: st.mtimeMs, entries: result.entries };
+        return result.entries;
+    }
+    const store = {
         append(entry, appendOptions) {
             const operation = appendChain
                 .catch(() => undefined)
                 .then(async () => {
                 if (options.createDirectory !== false)
                     await mkdir(dirname(path), { recursive: true });
-                const readResult = await readJsonlSessionEntries(path);
+                let beforeSize = 0;
+                try {
+                    beforeSize = (await stat(path)).size;
+                }
+                catch (error) {
+                    if (!isNodeErrorCode(error, "ENOENT"))
+                        throw error;
+                }
+                const readResult = await readParsed();
                 if (readResult.errors.length > 0) {
                     const first = readResult.errors[0];
                     throw new Error(`Invalid JSONL at line ${first.line}: ${first.message}`);
@@ -39,23 +86,30 @@ export function createJsonlSessionStore(pathOrOptions) {
                 if (entries.some((existing) => existing.id === entry.id))
                     throw new Error(`Duplicate session entry id: ${entry.id}`);
                 if (dedupKey !== undefined)
-                    idempotencySeen.add(dedupKey);
-                await appendFile(path, `${JSON.stringify(entry)}\n`, "utf8");
+                    rememberIdempotencyKey(idempotencySeen, dedupKey);
+                const line = `${JSON.stringify(entry)}\n`;
+                await appendFile(path, line, "utf8");
+                const info = await stat(path);
+                if (info.size === beforeSize + Buffer.byteLength(line)) {
+                    cache = { size: info.size, mtimeMs: info.mtimeMs, entries: entries.concat(entry) };
+                }
+                else {
+                    cache = undefined;
+                }
             });
             appendChain = operation.catch(() => undefined);
             return operation;
         },
         async list(sessionId) {
-            return (await readEntries(path)).filter((entry) => entry.sessionId === sessionId);
+            return (await readEntries()).filter((entry) => entry.sessionId === sessionId);
         },
         async get(id) {
-            return findEntry(path, id);
+            return (await readEntries()).find((entry) => entry.id === id);
         },
         async searchSessions(query) {
-            // ponytail: no index - every search reads and parses the file (O(corpus) time and memory), the
-            // recommended indexed paths are the SQLite/Postgres adapters. Corrupt lines are quarantined
-            // exactly as in list()/get(), and the contract linear caps bound entries/text scanned.
-            const { entries } = await readJsonlSessionEntries(path);
+            // ponytail: no index. Cache miss still reads and parses the file (O(corpus)); hit reuses the
+            // parsed array. Indexed path is SQLite/Postgres. Corrupt lines stay quarantined like list()/get().
+            const entries = await readEntries();
             const bySession = new Map();
             const leafBySession = new Map();
             for (const entry of entries) {
@@ -69,6 +123,8 @@ export function createJsonlSessionStore(pathOrOptions) {
             return searchLinearSessions(bySession, leafBySession, query);
         },
     };
+    Object.defineProperty(store, JSONL_FILE_READS, { get: () => fileReads });
+    return store;
 }
 /** Read a JSONL session file and return both valid entries and per-line parse errors. */
 export async function readJsonlSessionEntries(path) {
@@ -94,12 +150,6 @@ export async function readJsonlSessionEntries(path) {
     }
     return { entries, errors };
 }
-async function findEntry(path, id) {
-    return (await readEntries(path)).find((entry) => entry.id === id);
-}
-async function readEntries(path) {
-    return (await readJsonlSessionEntries(path)).entries;
-}
 function parseEntry(line, lineNumber) {
     let parsed;
     try {

package/dist/run-limits.d.ts

@@ -51,13 +51,19 @@ export declare class RunLimitTracker {
     private exceed;
 }
 export declare function createRunLimitTracker(limits: RunLimits | undefined, options?: RunLimitTrackerOptions): RunLimitTracker;
+/**
+ * Attribution carried by a limit death (plan 087 T2, plan 108 T5): the `budget_exhausted` payload
+ * without `limit`, which `AgentRunResult.limit` / `child_failed.limit` already carry.
+ */
+export interface BudgetExhaustionAttribution {
+    readonly consumed: BudgetConsumedCounters;
+    readonly closestOtherAxes: readonly BudgetAxisUsage[];
+    readonly recentToolCalls: readonly ToolCallSummary[];
+}
 /**
  * Build the `budget_exhausted` payload (plan 087 T2): which axis fired, the counters a host reads
  * first, the closest other axes, and the last dispatched tool calls (hashes only).
  */
-export declare function describeBudgetExhaustion(tracker: RunLimitTracker, breach: RunLimitBreach, recentToolCalls: readonly ToolCallSummary[]): {
-    limit: RunLimitName;
-    consumed: BudgetConsumedCounters;
-    closestOtherAxes: BudgetAxisUsage[];
-    recentToolCalls: ToolCallSummary[];
+export declare function describeBudgetExhaustion(tracker: RunLimitTracker, breach: RunLimitBreach, recentToolCalls: readonly ToolCallSummary[]): BudgetExhaustionAttribution & {
+    readonly limit: RunLimitName;
 };

package/dist/session-stores.js

@@ -27,11 +27,11 @@ async function readBranchFromReader(reader, query) {
         if (!cursor)
             break;
     }
-    // Reuse the validated in-memory walk: the reader returns the ancestor SET (any order);
-    // indexEntries + the parentId walk order it and still reject missing parents / dupes.
-    return getSessionBranchEntriesCore(items, { leafId: query.leafId });
+    // Reader returns an ancestor set in any order. Order once and keep those objects.
+    // Detachment is the store's clone (readBranchPath / list), not a second walk here.
+    return orderBranch(items, { leafId: query.leafId });
 }
-function getSessionBranchEntriesCore(entries, options = {}, index = indexEntries(entries)) {
+function orderBranch(entries, options = {}, index = indexEntries(entries)) {
     const leafId = options.leafId ?? entries.at(-1)?.id;
     if (!leafId)
         return [];
@@ -45,7 +45,11 @@ function getSessionBranchEntriesCore(entries, options = {}, index = indexEntries
         branch.push(entry);
         id = entry.parentId;
     }
-    return branch.reverse().map(cloneEntry);
+    branch.reverse();
+    return branch;
+}
+function getSessionBranchEntriesCore(entries, options = {}, index = indexEntries(entries)) {
+    return orderBranch(entries, options, index).map(cloneEntry);
 }
 export function listSessionBranches(entries) {
     const index = indexEntries(entries);
@@ -60,13 +64,15 @@ export function rebuildSessionContext(input, options = {}) {
     return rebuildSessionContextCore(input, options);
 }
 async function rebuildSessionContextFromReader(reader, query) {
-    // ponytail: pass the drained branch back through the sync core so compaction logic has ONE
-    // code path; the redundant re-walk is O(branch length) and branch chains are short.
-    const branch = await readBranchFromReader(reader, query);
-    return rebuildSessionContextCore(branch, { leafId: query.leafId });
+    // ponytail: one order pass on the reader's pages. No second walk and no second clone —
+    // stores that implement readBranchPath already detach. Upgrade path: clone here again if a
+    // host reader returns live store objects and a snapshot mutation is observed in the store.
+    return snapshotFromBranch(await readBranchFromReader(reader, query));
 }
 function rebuildSessionContextCore(entries, options = {}) {
-    const branch = getSessionBranchEntriesCore(entries, options);
+    return snapshotFromBranch(getSessionBranchEntriesCore(entries, options));
+}
+function snapshotFromBranch(branch) {
     const compaction = [...branch]
         .reverse()
         .find((entry) => entry.kind === "compaction" && entry.summary && isCompactionEntryData(entry.data));
@@ -90,7 +96,7 @@ function rebuildSessionContextCore(entries, options = {}) {
         if (entry.id === compaction.id)
             continue;
         if (entry.kind === "message" && entry.message && (afterThrough || keepIds.has(entry.id)))
-            messages.push(cloneEntry(entry.message));
+            messages.push(entry.message);
         if (entry.kind === "summary" && entry.summary && afterThrough)
             summaries.push(entry.summary);
     }
@@ -135,6 +141,18 @@ export function createMemorySessionStore(initialEntries = [], options = {}) {
                 throw new SessionSearchUnsupportedError();
             return searchLinearSessions(bySession, leafBySession, query, searchCaps);
         },
+        async readBranchPath(query) {
+            const entries = bySession.get(query.sessionId) ?? [];
+            const leafId = query.leafId ?? tipLeafId(entries);
+            if (!leafId)
+                return { items: [] };
+            const chain = orderBranch(entries, { leafId });
+            const start = query.cursor !== undefined ? decodeBranchOffset(query.cursor) : 0;
+            const limit = query.limit ?? chain.length;
+            const items = chain.slice(start, start + limit).map(cloneEntry);
+            const next = start + items.length;
+            return { items, nextCursor: next < chain.length ? String(next) : undefined };
+        },
     };
     function add(entry, options) {
         // ponytail: idempotency dedup keyed on (session, key, expectedParentId) so a
@@ -167,7 +185,7 @@ export function createMemorySessionStore(initialEntries = [], options = {}) {
         if (byId.has(entry.id))
             throw new Error(`Duplicate session entry id: ${entry.id}`);
         if (dedupKey !== undefined)
-            idempotencySeen.add(dedupKey);
+            rememberIdempotencyKey(idempotencySeen, dedupKey);
         byId.set(entry.id, entry);
         const entries = bySession.get(entry.sessionId) ?? [];
         entries.push(entry);
@@ -352,9 +370,40 @@ function isAfterSearchCursor(hit, cursor, order) {
     }
     return at < cursor.updatedAt || (at === cursor.updatedAt && hit.sessionId < cursor.sessionId);
 }
+/** Dedup only covers retries near the append. Older keys append as new entries. */
+const IDEMPOTENCY_SEEN_MAX = 4_096;
+function rememberIdempotencyKey(seen, key) {
+    if (seen.size >= IDEMPOTENCY_SEEN_MAX) {
+        const oldest = seen.values().next().value;
+        if (oldest !== undefined)
+            seen.delete(oldest);
+    }
+    seen.add(key);
+}
 function cloneEntry(entry) {
     return structuredClone(entry);
 }
+function decodeBranchOffset(cursor) {
+    const value = Number(cursor);
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error("Invalid branch pagination cursor");
+    return value;
+}
+/** Tip with the latest timestamp, then highest id. Matches SQLite `findLatestLeafId`. */
+function tipLeafId(entries) {
+    const parents = new Set();
+    for (const entry of entries)
+        if (entry.parentId)
+            parents.add(entry.parentId);
+    let best;
+    for (const entry of entries) {
+        if (parents.has(entry.id))
+            continue;
+        if (!best || entry.timestamp > best.timestamp || (entry.timestamp === best.timestamp && entry.id > best.id))
+            best = entry;
+    }
+    return best?.id;
+}
 function isCompactionEntryData(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;

package/dist/testing/prefix-stability-conformance.d.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig, Skill } from "../contracts.js";
+import type { AgentConfig, Message, ProviderRequest, Skill } from "../contracts.js";
 export interface PrefixStabilityConformanceOptions {
     /**
      * The host's own agent config, minus `provider`, `providerSource`, and `skills`:
@@ -25,6 +25,13 @@ export interface PrefixStabilityConformanceOptions {
      * fixture was supposed to invalidate the prefix, so a run that never did cannot pass vacuously.
      */
     readonly allowedResets?: number;
+    /**
+     * Install a runner-owned fixture tool (name constant) that returns exactly this many bytes of
+     * generated text, and add a second tool call for it alongside `load_skill` in the same round, so
+     * the attention compiler's tool-result stage has one row worth stubbing. The payload is
+     * `"x".repeat(bytes)`, never host content. Unset: the capture is byte-identical to today.
+     */
+    readonly foldableToolResultBytes?: number;
 }
 export interface PrefixStabilityConformanceResult {
     /** Provider requests captured by the fixture (two per turn: skill load, then completion). */
@@ -43,7 +50,43 @@ export interface PrefixStabilityConformanceResult {
      * prefix instead of appending. Empty when every gap stayed above the minimum.
      */
     readonly resets: readonly number[];
+    /**
+     * One row per `resets` entry, same order. `fraction` is the metric `assertOn` selected;
+     * `cacheableFraction` is the tail-excluded fraction for that pair. Empty when `resets` is.
+     */
+    readonly resetDetails: readonly PrefixStabilityResetDetail[];
+}
+export interface ScorePrefixStabilityOptions {
+    /** Session tail map. Omitted or unmatched: both fractions stay equal — never a fabricated `1`. */
+    readonly tailSegments?: ReadonlyMap<string, Message>;
+    /** Minimum shared byte-prefix fraction. Default `0.95`. Selects which pairs land in `resets`. */
+    readonly minContinuity?: number;
+    /**
+     * Which fraction `resets` follows. Default `"providerPrefix"` (the wire prefix). The runner
+     * passes its own `assertOn` so fixture resets stay on the selected metric without a second pass.
+     */
+    readonly assertOn?: "providerPrefix" | "cacheablePrefix";
+}
+/** One reset: index plus both fractions. Numbers only — no message text. */
+export interface PrefixStabilityResetDetail {
+    /** 1-based index of the later request in the pair. */
+    readonly request: number;
+    /** Fraction of the metric `assertOn` selected for the pair. Default: provider-visible. */
+    readonly fraction: number;
+    /** The same pair with tail segments removed. */
+    readonly cacheableFraction: number;
+}
+export interface PrefixStabilitySample {
+    readonly minContinuity: number;
+    readonly cacheableContinuity: number;
+    readonly resets: readonly number[];
+    readonly resetDetails: readonly PrefixStabilityResetDetail[];
 }
+/**
+ * Score an already-captured request list. One pass, no session, no provider call.
+ * A wrong `tailSegments` map yields a wrong number, not a throw.
+ */
+export declare function scorePrefixStability(requests: readonly ProviderRequest[], options?: ScorePrefixStabilityOptions): PrefixStabilitySample;
 /**
  * Drive a real session through two staggered skill loads and assert that each
  * provider request keeps a byte-identical leading prefix (messages **and** tool