praxis-agent 0.66.0 → 0.67.0

package/dist/application/compaction-accounting.d.ts

@@ -0,0 +1,49 @@
+import type { TranscriptEvent } from '../core/transcript-event.js';
+import type { ModelPricingRegistry } from '../core/usage.js';
+import type { ClaudeCostStateStore } from '../persistence/claude-cost-state-store.js';
+import type { CompactionReceiptStore } from '../persistence/native-compaction-receipt-store.js';
+import { ClaudeSessionCostTracker } from './session-cost-tracker.js';
+import type { TurnCompactionMetric } from './turn-accounting.js';
+import { type CompactionTrigger } from './compaction-errors.js';
+export interface CompactionAccountingOptions {
+    readonly sessionId: string;
+    readonly tracker: ClaudeSessionCostTracker;
+    readonly pricing?: ModelPricingRegistry;
+    readonly receiptStore?: CompactionReceiptStore;
+    readonly costStateStore?: Pick<ClaudeCostStateStore, 'save'>;
+    readonly readTranscript?: () => Promise<readonly TranscriptEvent[]>;
+    readonly createId?: () => string;
+}
+export interface PreparedCompactionTransaction {
+    readonly receiptId: string;
+    readonly boundaryId: string;
+    readonly summaryId: string;
+    readonly commit: (receipt: {
+        readonly kind: 'compaction';
+        readonly boundaryId: string;
+        readonly summaryId: string;
+    }) => Promise<void>;
+}
+export declare class CompactionAccounting {
+    private readonly sessionId;
+    private readonly tracker;
+    private readonly pricing;
+    private readonly receiptStore;
+    private readonly costStateStore;
+    private readonly readTranscript;
+    private readonly createId;
+    private recovered;
+    private recoveryPromise;
+    private recoveredReceipts;
+    private appliedReceipts;
+    constructor(options: CompactionAccountingOptions);
+    recover(): Promise<void>;
+    private recoverOnce;
+    prepare(input: {
+        readonly trigger: CompactionTrigger;
+        readonly metric: TurnCompactionMetric;
+    }): Promise<PreparedCompactionTransaction>;
+    private recoveryError;
+    private error;
+}
+//# sourceMappingURL=compaction-accounting.d.ts.map

package/dist/application/compaction-accounting.js

@@ -0,0 +1,349 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { usageCostUsd } from '../core/usage.js';
+import { ClaudeSessionCostTracker } from './session-cost-tracker.js';
+import { CompactionTransactionError, } from './compaction-errors.js';
+function clone(value) {
+    return structuredClone(value);
+}
+function validTransactionId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/u.test(value);
+}
+function fingerprint(snapshot) {
+    const modelUsage = Object.fromEntries(Object.entries(snapshot.modelUsage).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+    const stable = {
+        sessionId: snapshot.sessionId,
+        totalCostUsd: snapshot.totalCostUsd,
+        apiDurationMs: snapshot.apiDurationMs,
+        apiDurationWithoutRetriesMs: snapshot.apiDurationWithoutRetriesMs,
+        toolDurationMs: snapshot.toolDurationMs,
+        linesAdded: snapshot.linesAdded,
+        linesRemoved: snapshot.linesRemoved,
+        modelUsage,
+        hasUnknownModelCost: snapshot.hasUnknownModelCost,
+    };
+    return createHash('sha256').update(JSON.stringify(stable)).digest('hex');
+}
+function meaningful(usage) {
+    return [
+        usage.inputTokens,
+        usage.outputTokens,
+        usage.cacheReadInputTokens,
+        usage.cacheCreationInputTokens,
+        usage.cacheCreationInputTokens1h,
+        usage.webSearchRequests,
+    ].some((value) => typeof value === 'number' && value > 0);
+}
+function applyMetric(tracker, metric, costUsd) {
+    if (meaningful(metric.usage)) {
+        if (!metric.model?.trim())
+            throw new TypeError('Auto compact usage requires a nonblank model identity');
+        tracker.recordTurn({
+            model: metric.model,
+            usage: metric.usage,
+            ...(costUsd === null ? {} : { costUsd }),
+            ...(metric.usage.webSearchRequests === undefined
+                ? {}
+                : { webSearchRequests: metric.usage.webSearchRequests }),
+            apiDurationMs: metric.durationApiMs,
+            apiDurationWithoutRetriesMs: metric.durationApiWithoutRetriesMs,
+        });
+    }
+    else
+        tracker.recordDurations({
+            apiDurationMs: metric.durationApiMs,
+            apiDurationWithoutRetriesMs: metric.durationApiWithoutRetriesMs,
+        });
+}
+function compactPair(events, receipt) {
+    const boundaries = events.filter((event) => event.id === receipt.boundaryId);
+    const summaries = events.filter((event) => event.id === receipt.summaryId);
+    if (boundaries.length === 0 && summaries.length === 0)
+        return null;
+    if (boundaries.length !== 1 || summaries.length !== 1)
+        throw new Error('Compaction receipt has partial or duplicate Transcript evidence');
+    const matched = events.some((event, index) => {
+        const summary = events[index + 1];
+        return (event.kind === 'context-boundary' &&
+            event.id === receipt.boundaryId &&
+            event.parentId === null &&
+            event.sessionId === receipt.sessionId &&
+            event.trigger === receipt.trigger &&
+            event.durationMs === receipt.metric.durationApiMs &&
+            summary?.kind === 'context-summary' &&
+            summary.id === receipt.summaryId &&
+            summary.parentId === receipt.boundaryId &&
+            summary.sessionId === receipt.sessionId);
+    });
+    if (!matched)
+        throw new Error('Compaction receipt Transcript evidence does not match boundary and summary');
+    return events.findIndex((event, index) => {
+        const summary = events[index + 1];
+        return event.id === receipt.boundaryId && summary?.id === receipt.summaryId;
+    });
+}
+export class CompactionAccounting {
+    sessionId;
+    tracker;
+    pricing;
+    receiptStore;
+    costStateStore;
+    readTranscript;
+    createId;
+    recovered = false;
+    recoveryPromise;
+    recoveredReceipts = new Set();
+    appliedReceipts = new Set();
+    constructor(options) {
+        this.sessionId = options.sessionId;
+        this.tracker = options.tracker;
+        this.pricing = options.pricing;
+        this.receiptStore = options.receiptStore;
+        this.costStateStore = options.costStateStore;
+        this.readTranscript = options.readTranscript;
+        this.createId = options.createId ?? randomUUID;
+    }
+    async recover() {
+        if (this.recovered)
+            return;
+        if (this.recoveryPromise)
+            return this.recoveryPromise;
+        this.recoveryPromise = this.recoverOnce().catch((cause) => {
+            if (cause instanceof CompactionTransactionError)
+                throw cause;
+            throw this.error('auto', 'recovery', 'indeterminate', 'blocked', cause);
+        });
+        try {
+            await this.recoveryPromise;
+            this.recovered = true;
+        }
+        finally {
+            this.recoveryPromise = undefined;
+        }
+    }
+    async recoverOnce() {
+        if (!this.receiptStore)
+            return;
+        if (!this.readTranscript)
+            throw this.error('auto', 'recovery', 'indeterminate', 'blocked', new Error('Compaction recovery requires the complete native Transcript'));
+        const events = await this.readTranscript();
+        const rows = await this.receiptStore.list(this.sessionId);
+        const committed = [];
+        for (const row of rows) {
+            const receipt = row.receipt;
+            if (receipt.sessionId !== this.sessionId)
+                throw this.recoveryError(receipt, new Error('Compaction receipt session does not match recovery'));
+            let index;
+            try {
+                index = compactPair(events, receipt);
+            }
+            catch (cause) {
+                throw this.recoveryError(receipt, cause);
+            }
+            if (index === null)
+                continue;
+            committed.push({ row, index });
+        }
+        committed.sort((a, b) => a.index - b.index);
+        if (!this.costStateStore) {
+            const preflight = new ClaudeSessionCostTracker({
+                sessionId: this.sessionId,
+                restored: this.tracker.snapshot(),
+            });
+            for (const { row } of committed) {
+                if (this.appliedReceipts.has(row.receipt.receiptId))
+                    continue;
+                try {
+                    applyMetric(preflight, row.receipt.metric, row.receipt.costUsd);
+                }
+                catch (cause) {
+                    throw this.recoveryError(row.receipt, cause);
+                }
+            }
+            for (const { row } of committed) {
+                const receipt = row.receipt;
+                if (this.recoveredReceipts.has(receipt.receiptId))
+                    continue;
+                if (!this.appliedReceipts.has(receipt.receiptId)) {
+                    const check = new ClaudeSessionCostTracker({
+                        sessionId: this.sessionId,
+                        restored: this.tracker.snapshot(),
+                    });
+                    const before = fingerprint(this.tracker.snapshot());
+                    try {
+                        applyMetric(check, receipt.metric, receipt.costUsd);
+                    }
+                    catch (cause) {
+                        throw this.recoveryError(receipt, cause);
+                    }
+                    if (before === receipt.before &&
+                        fingerprint(check.snapshot()) !== receipt.after)
+                        throw this.recoveryError(receipt, new Error('Compaction receipt after fingerprint mismatch'));
+                    try {
+                        applyMetric(this.tracker, receipt.metric, receipt.costUsd);
+                    }
+                    catch (cause) {
+                        throw this.recoveryError(receipt, cause);
+                    }
+                    this.appliedReceipts.add(receipt.receiptId);
+                }
+                if (!row.acknowledged) {
+                    try {
+                        await this.receiptStore.acknowledge(this.sessionId, receipt.receiptId);
+                    }
+                    catch (cause) {
+                        throw this.recoveryError(receipt, cause, 'reconcile');
+                    }
+                }
+                this.recoveredReceipts.add(receipt.receiptId);
+            }
+            return;
+        }
+        const pending = new Map(committed
+            .filter(({ row }) => !row.acknowledged)
+            .map(({ row }) => [row.receipt.receiptId, row]));
+        while (pending.size > 0) {
+            const candidates = [...pending.values()].filter((row) => {
+                const current = fingerprint(this.tracker.snapshot());
+                return current === row.receipt.before || current === row.receipt.after;
+            });
+            const candidate = candidates[0];
+            const fallback = pending.values().next().value;
+            if (candidates.length !== 1 || !candidate) {
+                if (!fallback)
+                    throw this.error('auto', 'recovery', 'indeterminate', 'blocked', new Error('Compaction receipt chain is empty'));
+                throw this.recoveryError(fallback.receipt, new Error(candidates.length > 1
+                    ? 'Ambiguous compaction receipt chain'
+                    : 'No compaction receipt chain candidate'));
+            }
+            const receipt = candidate.receipt;
+            const now = fingerprint(this.tracker.snapshot());
+            if (now === receipt.before) {
+                const check = new ClaudeSessionCostTracker({
+                    sessionId: this.sessionId,
+                    restored: this.tracker.snapshot(),
+                });
+                try {
+                    applyMetric(check, receipt.metric, receipt.costUsd);
+                }
+                catch (cause) {
+                    throw this.recoveryError(receipt, cause);
+                }
+                if (fingerprint(check.snapshot()) !== receipt.after)
+                    throw this.recoveryError(receipt, new Error('Compaction receipt after fingerprint mismatch'));
+                try {
+                    applyMetric(this.tracker, receipt.metric, receipt.costUsd);
+                }
+                catch (cause) {
+                    throw this.recoveryError(receipt, cause);
+                }
+            }
+            try {
+                await this.costStateStore.save(this.tracker.snapshot());
+                await this.receiptStore.acknowledge(this.sessionId, receipt.receiptId);
+            }
+            catch (cause) {
+                throw this.recoveryError(receipt, cause, 'reconcile');
+            }
+            this.recoveredReceipts.add(receipt.receiptId);
+            pending.delete(receipt.receiptId);
+        }
+    }
+    async prepare(input) {
+        const metric = clone(input.metric);
+        const preflight = new ClaudeSessionCostTracker({
+            sessionId: this.sessionId,
+            restored: this.tracker.snapshot(),
+        });
+        let fixedCost;
+        try {
+            const resolved = metric.model
+                ? this.pricing?.resolve(metric.model)
+                : undefined;
+            fixedCost = resolved ? usageCostUsd(metric.usage, resolved) : null;
+            applyMetric(preflight, metric, fixedCost);
+        }
+        catch (cause) {
+            throw this.error(input.trigger, 'validation', 'not_committed', 'none', cause);
+        }
+        const receiptId = this.createId();
+        const boundaryId = this.createId();
+        const summaryId = this.createId();
+        if (!validTransactionId(receiptId) ||
+            !validTransactionId(boundaryId) ||
+            !validTransactionId(summaryId) ||
+            new Set([receiptId, boundaryId, summaryId]).size !== 3)
+            throw this.error(input.trigger, 'validation', 'not_committed', 'blocked', new Error('Compaction transaction IDs must be safe, nonblank, and distinct'));
+        const before = fingerprint(this.tracker.snapshot());
+        const after = fingerprint(preflight.snapshot());
+        const receipt = {
+            version: 1,
+            receiptId,
+            sessionId: this.sessionId,
+            boundaryId,
+            summaryId,
+            trigger: input.trigger,
+            metric,
+            costUsd: fixedCost,
+            before,
+            after,
+        };
+        try {
+            await this.receiptStore?.prepare(receipt);
+        }
+        catch (cause) {
+            throw this.error(input.trigger, 'receipt_prepare', 'not_committed', 'retry', cause);
+        }
+        if (this.receiptStore)
+            this.recovered = false;
+        let used = false;
+        return {
+            receiptId,
+            boundaryId,
+            summaryId,
+            commit: async (appendReceipt) => {
+                if (used)
+                    throw this.error(input.trigger, 'accounting_commit', 'committed', 'reconcile', new Error('Prepared compaction transaction was already committed'));
+                if (typeof appendReceipt !== 'object' ||
+                    appendReceipt === null ||
+                    appendReceipt.kind !== 'compaction' ||
+                    appendReceipt.boundaryId !== boundaryId ||
+                    appendReceipt.summaryId !== summaryId)
+                    throw this.error(input.trigger, 'transcript_commit', 'indeterminate', 'blocked', new Error('Transcript compaction receipt does not match prepared IDs'));
+                used = true;
+                try {
+                    const check = new ClaudeSessionCostTracker({
+                        sessionId: this.sessionId,
+                        restored: this.tracker.snapshot(),
+                    });
+                    applyMetric(check, metric, fixedCost);
+                    if (fingerprint(check.snapshot()) !== after)
+                        throw this.error(input.trigger, 'accounting_commit', 'indeterminate', 'blocked', new Error('Compaction receipt after fingerprint mismatch'));
+                    applyMetric(this.tracker, metric, fixedCost);
+                    this.appliedReceipts.add(receiptId);
+                }
+                catch (cause) {
+                    this.recovered = false;
+                    throw this.error(input.trigger, 'accounting_commit', 'indeterminate', 'blocked', cause);
+                }
+                try {
+                    if (this.costStateStore)
+                        await this.costStateStore.save(this.tracker.snapshot());
+                    if (this.receiptStore)
+                        await this.receiptStore.acknowledge(this.sessionId, receiptId);
+                }
+                catch (cause) {
+                    this.recovered = false;
+                    throw this.error(input.trigger, 'accounting_commit', 'committed', 'reconcile', cause);
+                }
+                this.recoveredReceipts.add(receiptId);
+            },
+        };
+    }
+    recoveryError(receipt, cause, disposition = 'blocked') {
+        return this.error(receipt.trigger, 'recovery', 'indeterminate', disposition, cause);
+    }
+    error(trigger, phase, durableState, recoveryDisposition, cause) {
+        return new CompactionTransactionError(`Compaction ${phase} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { trigger, phase, durableState, recoveryDisposition }, cause);
+    }
+}
+//# sourceMappingURL=compaction-accounting.js.map

package/dist/application/compaction-errors.d.ts

@@ -0,0 +1,21 @@
+export type CompactionTrigger = 'auto' | 'manual';
+export type CompactionPhase = 'validation' | 'generation' | 'receipt_prepare' | 'transcript_commit' | 'accounting_commit' | 'post_commit' | 'recovery';
+export type CompactionDurableState = 'not_committed' | 'committed' | 'indeterminate';
+export type CompactionRecoveryDisposition = 'none' | 'retry' | 'reconcile' | 'blocked';
+export interface CompactionTransactionErrorMetadata {
+    readonly trigger: CompactionTrigger;
+    readonly phase: CompactionPhase;
+    readonly durableState: CompactionDurableState;
+    readonly recoveryDisposition: CompactionRecoveryDisposition;
+}
+/** A classified compaction failure. The original failure remains available as
+ * `cause`, preserving provider error identity and retry/status metadata. */
+export declare class CompactionTransactionError extends Error {
+    readonly name = "CompactionTransactionError";
+    readonly metadata: Readonly<CompactionTransactionErrorMetadata>;
+    readonly cause: unknown;
+    constructor(message: string, metadata: CompactionTransactionErrorMetadata, cause?: unknown);
+}
+export declare function isCompactionTransactionError(error: unknown): error is CompactionTransactionError;
+export declare function classifyCompactionError(error: unknown, metadata: CompactionTransactionErrorMetadata): CompactionTransactionError;
+//# sourceMappingURL=compaction-errors.d.ts.map

package/dist/application/compaction-errors.js

@@ -0,0 +1,24 @@
+import { AgentRunCancelledError } from '../core/runtime.js';
+/** A classified compaction failure. The original failure remains available as
+ * `cause`, preserving provider error identity and retry/status metadata. */
+export class CompactionTransactionError extends Error {
+    name = 'CompactionTransactionError';
+    metadata;
+    cause;
+    constructor(message, metadata, cause) {
+        super(message, { cause });
+        this.metadata = Object.freeze({ ...metadata });
+        this.cause = cause;
+    }
+}
+export function isCompactionTransactionError(error) {
+    return error instanceof CompactionTransactionError;
+}
+export function classifyCompactionError(error, metadata) {
+    if (error instanceof AgentRunCancelledError)
+        throw error;
+    if (error instanceof CompactionTransactionError)
+        return error;
+    return new CompactionTransactionError(`Compaction ${metadata.phase} failed: ${error instanceof Error ? error.message : String(error)}`, metadata, error);
+}
+//# sourceMappingURL=compaction-errors.js.map

package/dist/application/context-engine.js

@@ -1,6 +1,7 @@
 import { AgentRunCancelledError, } from '../core/runtime.js';
 import { contextRecoveryMadeProgress, isPromptTooLongError, } from '../core/context-budget.js';
 import { StaleContextGenerationError } from './context-preparation.js';
+import { CompactionTransactionError } from './compaction-errors.js';
 function assertSignal(signal) {
     if (signal?.aborted)
         throw new AgentRunCancelledError();
@@ -100,7 +101,15 @@ export class ContextEngine {
                 cause instanceof AgentRunCancelledError ||
                 cause instanceof StaleContextGenerationError)
                 throw cause;
-            return { kind: 'exhausted', error };
+            if (cause instanceof CompactionTransactionError) {
+                const metadata = cause.metadata;
+                if (metadata.trigger !== 'auto' ||
+                    metadata.phase !== 'generation' ||
+                    metadata.durableState !== 'not_committed')
+                    throw cause;
+                return { kind: 'exhausted', error };
+            }
+            throw cause;
         }
     }
     observeUsage(usage, messages, tools) {

package/dist/application/native-session-transcript.d.ts

@@ -28,6 +28,9 @@ export interface NativeCompactionAppend {
     readonly direction?: 'from' | 'up_to';
     readonly messagesSummarized?: number;
     readonly preservePrefix?: boolean;
+    /** IDs reserved by the compaction accounting transaction. */
+    readonly boundaryId?: string;
+    readonly summaryId?: string;
 }
 export type NativeInterruption = {
     readonly kind: 'complete' | 'none';

package/dist/application/native-session-transcript.js

@@ -1,5 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { activeEvents, projectActiveMessages, unresolvedActiveToolCallIds, } from './transcript-projection.js';
+function isSafeNativeId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/u.test(value);
+}
 export class NativeSessionTranscript {
     sessionId;
     store;
@@ -275,8 +278,22 @@ export class NativeSessionTranscript {
                     const events = records.map((record) => record.event);
                     if (unresolvedActiveToolCallIds(projectActiveMessages(events, activeId)).length > 0)
                         throw new Error('Cannot compact a native transcript with unresolved tool calls');
-                    const boundaryId = createUniqueId();
-                    const summaryId = createUniqueId();
+                    const boundaryId = input.boundaryId ?? createUniqueId();
+                    const summaryId = input.summaryId ?? createUniqueId();
+                    if (typeof boundaryId !== 'string' ||
+                        boundaryId.trim() === '' ||
+                        typeof summaryId !== 'string' ||
+                        summaryId.trim() === '' ||
+                        !isSafeNativeId(boundaryId) ||
+                        !isSafeNativeId(summaryId) ||
+                        boundaryId === summaryId ||
+                        (input.boundaryId !== undefined && usedIds.has(boundaryId)) ||
+                        (input.summaryId !== undefined && usedIds.has(summaryId)))
+                        throw new Error('Native compaction boundary and summary IDs must be nonblank, distinct, and unused');
+                    if (input.boundaryId !== undefined)
+                        usedIds.add(boundaryId);
+                    if (input.summaryId !== undefined)
+                        usedIds.add(summaryId);
                     const boundary = {
                         kind: 'context-boundary',
                         id: boundaryId,
@@ -353,9 +370,24 @@ export class NativeSessionTranscript {
                         summary,
                         ...(suffixEvent === undefined ? [] : [suffixEvent]),
                     ];
-                    const appended = await nativeLease.appendMany(tail, compactedEvents);
-                    if (appended.status === 'conflict')
+                    let appended;
+                    try {
+                        appended = await nativeLease.appendMany(tail, compactedEvents);
+                    }
+                    catch (error) {
+                        if (input.boundaryId !== undefined)
+                            usedIds.delete(boundaryId);
+                        if (input.summaryId !== undefined)
+                            usedIds.delete(summaryId);
+                        throw error;
+                    }
+                    if (appended.status === 'conflict') {
+                        if (input.boundaryId !== undefined)
+                            usedIds.delete(boundaryId);
+                        if (input.summaryId !== undefined)
+                            usedIds.delete(summaryId);
                         throw new Error(`native transcript append conflict: ${appended.reason}`);
+                    }
                     records.push({ event: boundary }, { event: summary }, ...(suffixEvent === undefined ? [] : [{ event: suffixEvent }]));
                     tail = appended.tail;
                     activeId = suffixEvent?.id ?? summaryId;

package/dist/application/session-service.d.ts

@@ -230,6 +230,7 @@ export declare class ClaudeSessionService {
     private activeProvider;
     private mcpClosePromise;
     private readonly sessionCostTrackers;
+    private readonly compactionAccountings;
     private activeCostSessionId;
     private closeCostSavePromise;
     private closeMetadataSavePromise;
@@ -354,6 +355,7 @@ export declare class ClaudeSessionService {
     private enqueueBackgroundNotifications;
     private store;
     private nativeStore;
+    private compactionAccounting;
     private assertSessionPersistence;
     private assertWritable;
     private assertTurnWritable;