praxis-agent 0.26.0 → 0.28.0

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

@@ -1,9 +1,14 @@
-import type { ModelMessage } from '../core/runtime.js';
+import { type ModelMessage } from '../core/runtime.js';
 /** Versioned, explicit progress state for one session's extracted memory. */
 export interface SessionMemoryState {
     schemaVersion: 1;
     initialized: boolean;
     lastObservedTokens: number;
+    /** Current-context growth baseline after a durable compaction reduction. */
+    growthBaselineTokens?: number;
+    /** Latest extraction attempt occupancy, successful or failed. Older
+     * sidecars omit it and fall back to the successful watermark. */
+    lastAttemptedTokens?: number;
     lastObservedToolCalls: number;
     lastSummarizedMessageId: string | null;
     extractionStartedAt: number | null;
@@ -19,6 +24,10 @@ export declare class SessionMemoryTimeoutError extends Error {
     constructor(message: string);
 }
 export declare function createFreshSessionMemoryState(): SessionMemoryState;
+export interface SessionMemorySnapshot {
+    state: SessionMemoryState;
+    summary: string;
+}
 export interface SessionMemoryStoreOptions {
     configRoot: string;
     sessionId: string;
@@ -35,13 +44,23 @@ export interface SessionMemoryStoreOptions {
  */
 export declare class SessionMemoryStore {
     private readonly directory;
+    private readonly artifactsDirectory;
     private readonly stateFile;
     private readonly summaryFile;
     constructor(options: SessionMemoryStoreOptions);
     load(): Promise<SessionMemoryState>;
+    /** Reads the pointer record once, then resolves exactly the artifact named
+     *  by that record. Concurrent commits cannot pair an old watermark with a
+     *  newer summary. */
+    loadSnapshot(): Promise<SessionMemorySnapshot>;
+    private loadRecord;
     loadSummary(): Promise<string>;
+    private loadSummaryForRecord;
     writeSummary(summary: string): Promise<void>;
-    writeState(state: SessionMemoryState): Promise<void>;
+    writeState(state: SessionMemoryState, summaryFile?: string): Promise<void>;
+    /** Writes an immutable summary artifact, then atomically commits its pointer
+     *  with the progress watermark. summary.md is a best-effort readable mirror. */
+    commitExtraction(state: SessionMemoryState, summary: string): Promise<void>;
     clear(): Promise<void>;
 }
 export interface SessionMemoryExtractorInput {
@@ -49,15 +68,18 @@ export interface SessionMemoryExtractorInput {
     tokens: number;
     toolCalls: number;
     messages?: readonly ModelMessage[];
+    signal: AbortSignal;
 }
 export type SessionMemoryExtractor = (input: SessionMemoryExtractorInput) => Promise<string> | string;
 export interface SessionMemoryControllerOptions {
     store: SessionMemoryStore;
     extractor: SessionMemoryExtractor;
+    onExtractionError?: (error: unknown) => void;
     initTokens?: number;
     updateTokens?: number;
     updateToolCalls?: number;
     waitTimeoutMs?: number;
+    staleExtractionMs?: number;
 }
 /**
  * Serialized extraction lifecycle for one session. Concurrent callers of
@@ -71,20 +93,23 @@ export declare class SessionMemoryController {
     private readonly updateTokens;
     private readonly updateToolCalls;
     private readonly waitTimeoutMs;
+    private readonly staleExtractionMs;
     private stateValue;
     private summaryValue;
     private inFlight;
+    private extractionController;
     private loading;
     private observedTokens;
+    private tokenBaseline;
+    private attemptTokenBaseline;
     private observedToolCalls;
+    private closed;
     constructor(options: SessionMemoryControllerOptions);
     observe(tokens: number, toolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
-    /**
-     * Adds non-negative deltas to the current cumulative observed totals and
-     * delegates to the serialized extraction path with those cumulative totals.
-     * The persisted counters only advance once an extraction succeeds.
-     */
-    observeDelta(inputTokens: number, toolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
+    /** Observes the current provider-visible context occupancy and a per-turn
+     *  tool-call delta. Unlike provider input-token deltas, occupancy may shrink
+     *  after compaction; that establishes a new growth baseline. */
+    observeContext(currentTokens: number, turnToolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
     /**
      * Records the observed totals and starts an extraction when the fixed
      * eligibility contract is met. Returns true when an extraction is running or
@@ -97,14 +122,22 @@ export declare class SessionMemoryController {
     state(): Promise<SessionMemoryState>;
     /**
      * Resolves when no extraction is running; rejects on extraction failure.
-     * Compact callers wait softly: if extraction outlives the bounded
-     * `waitTimeoutMs`, this resolves so compaction can proceed anyway.
+     * Normal turns do not await this diagnostic seam.
      */
     waitForIdle(): Promise<void>;
+    /** Compact consumes only the last committed artifact. It waits softly for a
+     *  useful extraction, swallows retryable failures, and cancels stale work. */
+    waitForCompact(): Promise<void>;
+    /** Cancels owned extraction work and waits only for the configured bounded
+     *  interval. A provider that ignores AbortSignal cannot hold service close. */
+    close(): Promise<void>;
     clear(): Promise<void>;
     private ensureLoaded;
     private loadState;
     private isExtractionDue;
     private runExtraction;
+    private assertOpen;
+    private rebaseAfterContextReduction;
+    private waitBoundedly;
 }
 //# sourceMappingURL=session-memory.d.ts.map