praxis-agent 0.24.1 → 0.25.0

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

@@ -85,11 +85,21 @@ export declare class SessionMemoryController {
      * The persisted counters only advance once an extraction succeeds.
      */
     observeDelta(inputTokens: number, toolCalls: 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
+     * was just scheduled; callers on normal turns never await the extraction.
+     */
+    private scheduleExtraction;
     /** Safe snapshot of the loaded durable summary; empty when none exists. */
     summary(): Promise<string>;
     /** Safe snapshot of the loaded session memory state. */
     state(): Promise<SessionMemoryState>;
-    /** Resolves when no extraction is running; rejects on failure or timeout. */
+    /**
+     * 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.
+     */
     waitForIdle(): Promise<void>;
     clear(): Promise<void>;
     private ensureLoaded;

package/dist/application/session-memory.js

@@ -2,6 +2,8 @@ import { readFile, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { isClaudeSessionId } from '../compatibility/claude/paths.js';
 import { writeFileAtomically } from '../platform/atomic-write.js';
+/** A persisted extraction this old is recovered as stale and safely re-extracted. */
+const STALE_EXTRACTION_THRESHOLD_MS = 60_000;
 export class SessionMemoryStateError extends Error {
     name = 'SessionMemoryStateError';
     constructor(message) {
@@ -170,8 +172,8 @@ export class SessionMemoryController {
         this.options = options;
         this.initTokens = options.initTokens ?? 10_000;
         this.updateTokens = options.updateTokens ?? 5_000;
-        this.updateToolCalls = options.updateToolCalls ?? 20;
-        this.waitTimeoutMs = options.waitTimeoutMs ?? 30_000;
+        this.updateToolCalls = options.updateToolCalls ?? 3;
+        this.waitTimeoutMs = options.waitTimeoutMs ?? 15_000;
         for (const [name, value] of [
             ['initTokens', this.initTokens],
             ['updateTokens', this.updateTokens],
@@ -204,22 +206,10 @@ export class SessionMemoryController {
             toolCalls < state.lastObservedToolCalls) {
             throw new SessionMemoryStateError(`Session memory observed counters regressed (tokens ${tokens} < ${state.lastObservedTokens}, toolCalls ${toolCalls} < ${state.lastObservedToolCalls})`);
         }
-        this.observedTokens = Math.max(this.observedTokens, tokens);
-        this.observedToolCalls = Math.max(this.observedToolCalls, toolCalls);
-        if (!this.isExtractionDue(this.observedTokens, this.observedToolCalls)) {
-            return false;
-        }
-        if (this.inFlight === null) {
-            const extraction = this.runExtraction(this.observedTokens, this.observedToolCalls, messageId, messages);
-            this.inFlight = extraction;
-            extraction
-                .catch(() => undefined)
-                .finally(() => {
-                if (this.inFlight === extraction)
-                    this.inFlight = null;
-            });
-        }
-        return true;
+        // A direct absolute observation reports a natural break when no tool calls
+        // have accumulated since the last successful extraction.
+        const naturalBreak = toolCalls === state.lastObservedToolCalls;
+        return this.scheduleExtraction(tokens, toolCalls, messageId, messages, naturalBreak);
     }
     /**
      * Adds non-negative deltas to the current cumulative observed totals and
@@ -241,7 +231,32 @@ export class SessionMemoryController {
         }
         this.observedTokens += inputTokens;
         this.observedToolCalls += toolCalls;
-        return this.observe(this.observedTokens, this.observedToolCalls, messageId, messages);
+        // A zero-tool-call turn is a natural break: the last assistant turn made
+        // no tool calls.
+        return this.scheduleExtraction(this.observedTokens, this.observedToolCalls, messageId, messages, toolCalls === 0);
+    }
+    /**
+     * Records the observed totals and starts an extraction when the fixed
+     * eligibility contract is met. Returns true when an extraction is running or
+     * was just scheduled; callers on normal turns never await the extraction.
+     */
+    scheduleExtraction(tokens, toolCalls, messageId, messages, naturalBreak) {
+        this.observedTokens = Math.max(this.observedTokens, tokens);
+        this.observedToolCalls = Math.max(this.observedToolCalls, toolCalls);
+        if (!this.isExtractionDue(this.observedTokens, this.observedToolCalls, naturalBreak)) {
+            return false;
+        }
+        if (this.inFlight === null) {
+            const extraction = this.runExtraction(this.observedTokens, this.observedToolCalls, messageId, messages);
+            this.inFlight = extraction;
+            extraction
+                .catch(() => undefined)
+                .finally(() => {
+                if (this.inFlight === extraction)
+                    this.inFlight = null;
+            });
+        }
+        return true;
     }
     /** Safe snapshot of the loaded durable summary; empty when none exists. */
     async summary() {
@@ -256,15 +271,19 @@ export class SessionMemoryController {
         }
         return { ...this.stateValue };
     }
-    /** Resolves when no extraction is running; rejects on failure or timeout. */
+    /**
+     * 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.
+     */
     async waitForIdle() {
         await this.ensureLoaded();
         const extraction = this.inFlight;
         if (extraction === null)
             return;
         let timer;
-        const timeout = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new SessionMemoryTimeoutError(`Session memory extraction did not complete within ${this.waitTimeoutMs}ms`)), this.waitTimeoutMs);
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, this.waitTimeoutMs);
         });
         try {
             await Promise.race([extraction, timeout]);
@@ -307,7 +326,7 @@ export class SessionMemoryController {
                 ...state,
                 extractionStartedAt: null,
                 extractionCompletedAt: null,
-                extractionError: elapsed >= this.waitTimeoutMs
+                extractionError: elapsed >= STALE_EXTRACTION_THRESHOLD_MS
                     ? `Session memory extraction is stale after ${elapsed}ms`
                     : 'Session memory extraction was interrupted',
             };
@@ -321,14 +340,18 @@ export class SessionMemoryController {
         this.observedToolCalls = this.stateValue.lastObservedToolCalls;
         this.summaryValue = summary;
     }
-    isExtractionDue(tokens, toolCalls) {
+    isExtractionDue(tokens, toolCalls, naturalBreak) {
         const state = this.stateValue;
         if (state === null)
             return false;
         if (!state.initialized)
             return tokens >= this.initTokens;
-        return (tokens - state.lastObservedTokens >= this.updateTokens ||
-            toolCalls - state.lastObservedToolCalls >= this.updateToolCalls);
+        // Unchanged context must not retrigger; tool-call growth alone is never
+        // enough without at least the update-token growth.
+        if (tokens - state.lastObservedTokens < this.updateTokens)
+            return false;
+        return (toolCalls - state.lastObservedToolCalls >= this.updateToolCalls ||
+            naturalBreak);
     }
     async runExtraction(tokens, toolCalls, messageId, messages) {
         const state = this.stateValue;

package/dist/application/session-service.js

@@ -871,7 +871,7 @@ export class ClaudeSessionService {
             ...(onDelta ? { onTextDelta: onDelta } : {}),
             onMetrics: (recorded) => this.recordAuxiliaryMetrics(activeSessionId, recorded),
         });
-        budget?.observeUsage(metrics.usage);
+        budget?.observeUsage(metrics.usage, messages);
         if (metrics.toolCalls.length > 0) {
             throw new Error('Side questions cannot call tools; press f to fork');
         }
@@ -3051,7 +3051,7 @@ export class ClaudeSessionService {
                     : undefined) ??
                     Object.values(result.modelUsage ?? {})[0] ??
                     result.usage;
-                budget?.observeUsage(observedUsage);
+                budget?.observeUsage(observedUsage, runtimeRequest.messages, definitions);
                 if (structuredCapture && structuredCapture.calls !== 1) {
                     throw new Error(`StructuredOutput must be called exactly once (received ${structuredCapture.calls})`);
                 }
@@ -3148,17 +3148,20 @@ export class ClaudeSessionService {
                 }
                 if (sessionMemory && finalLeafUuid) {
                     const turnInputTokens = result.usage?.inputTokens ?? 0;
+                    const warn = (error) => this.options.eventSink?.({
+                        type: 'warning',
+                        message: `Session memory extraction failed: ${error instanceof Error ? error.message : String(error)}`,
+                    });
                     try {
                         await sessionMemory.observeDelta(turnInputTokens, currentTurnToolCalls, finalLeafUuid, projectClaudeModelMessages(snapshot.entries));
-                        await sessionMemory.waitForIdle();
+                        // Normal turns schedule extraction without awaiting it; failures
+                        // surface as a warning while the sidecar stays retryable.
+                        sessionMemory.waitForIdle().catch(warn);
                     }
                     catch (error) {
-                        // A failed extraction must not fail the user turn; the sidecar
+                        // A failed observation must not fail the user turn; the sidecar
                         // retains a retryable error for the next observation.
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `Session memory extraction failed: ${error instanceof Error ? error.message : String(error)}`,
-                        });
+                        warn(error);
                     }
                 }
                 turnCompleted = true;
@@ -3852,6 +3855,10 @@ export class ClaudeSessionService {
         return new ContextBudget({
             contextWindowTokens,
             windowSource: 'capability',
+            onAccountingDiagnostic: (message) => this.options.eventSink?.({
+                type: 'warning',
+                message: `Context usage accounting: ${message}`,
+            }),
             ...(this.options.contextReserveTokens === undefined
                 ? {}
                 : { reserveTokens: this.options.contextReserveTokens }),

package/dist/application/subagent-service.js

@@ -1461,6 +1461,10 @@ export class ClaudeSubagentExecutor {
             const contextBudget = options.provider.capabilities.contextWindowTokens
                 ? new ContextBudget({
                     contextWindowTokens: options.provider.capabilities.contextWindowTokens,
+                    onAccountingDiagnostic: (message) => this.options.eventSink?.({
+                        type: 'warning',
+                        message: `Context usage accounting: ${message}`,
+                    }),
                     ...(this.options.contextReserveTokens === undefined
                         ? {}
                         : { reserveTokens: this.options.contextReserveTokens }),
@@ -1469,6 +1473,7 @@ export class ClaudeSubagentExecutor {
             const definitions = options.provider.capabilities.tools
                 ? runtimeTools.definitions()
                 : [];
+            let observedMessages;
             const assembleMessages = async () => {
                 const assembledContext = await this.options.contextAssembler?.assemble({
                     cwd,
@@ -1479,6 +1484,7 @@ export class ClaudeSubagentExecutor {
                     ...injectFirstUserMessageContext(projectClaudeModelMessages(snapshot.entries), assembledContext?.firstUserMessageContext),
                     ...preloadedSkills,
                 ];
+                observedMessages = messages;
                 if (contextBudget) {
                     contextBudget.assertFits(contextBudget.evaluate(messages, definitions));
                 }
@@ -1547,6 +1553,7 @@ export class ClaudeSubagentExecutor {
                     : {}),
                 ...(options.signal ? { signal: options.signal } : {}),
             });
+            contextBudget?.observeUsage(result.usage, observedMessages ?? [], definitions);
             this.options.eventSink?.({
                 type: 'task-progress',
                 taskId: options.agentId,

package/dist/compatibility/claude/fork.js

@@ -181,8 +181,10 @@ export function createClaudeNativeFork({ source, sourceSessionId, sessionId, res
             (metadata.direction === 'from' ||
                 metadata.direction === 'up_to'));
     });
+    const hasCompactHistory = source.some((entry) => entry.isCompactSummary === true ||
+        (entry.type === 'system' && entry.subtype === 'compact_boundary'));
     const activeSource = resumeSessionAt === undefined
-        ? hasSelectiveSummary
+        ? hasCompactHistory || hasSelectiveSummary
             ? selectClaudeActiveTranscript(source)
             : source
         : selectClaudeTranscriptAtMessage(source, resumeSessionAt);

package/dist/compatibility/claude/history.js

@@ -18,7 +18,11 @@ function latestLeafUuid(entries) {
             entry.isSidechain !== true);
         if (!hasNewDescendant)
             return summary.uuid;
-        break;
+        // After compaction the active leaf continues from the boundary's logical
+        // parent. Ignore unrelated physical entries that do not descend from the
+        // boundary and keep the compact summary as the leaf when none do.
+        const continuation = latestCompactBranchLeafUuid(entries, index + 1, boundary ? entryUuid(boundary) : null, summary.uuid);
+        return continuation === null ? summary.uuid : continuation;
     }
     for (let index = entries.length - 1; index >= 0; index -= 1) {
         const entry = entries[index];
@@ -33,6 +37,45 @@ function latestLeafUuid(entries) {
     }
     return null;
 }
+function latestCompactBranchLeafUuid(entries, fromIndex, boundaryUuid, summaryUuid) {
+    const byUuid = new Map();
+    for (const entry of entries) {
+        const uuid = entryUuid(entry);
+        if (uuid && entry.isSidechain !== true)
+            byUuid.set(uuid, entry);
+    }
+    for (let index = entries.length - 1; index >= fromIndex; index -= 1) {
+        const entry = entries[index];
+        if (!entry || entry.isSidechain === true)
+            continue;
+        const candidate = entry.type === 'last-prompt' && typeof entry.leafUuid === 'string'
+            ? entry.leafUuid
+            : entryUuid(entry);
+        if (candidate === null)
+            continue;
+        let uuid = candidate;
+        const seen = new Set();
+        while (uuid !== null) {
+            if (uuid === summaryUuid || uuid === boundaryUuid)
+                return candidate;
+            if (seen.has(uuid))
+                break;
+            seen.add(uuid);
+            const node = byUuid.get(uuid);
+            if (!node)
+                break;
+            uuid =
+                node.type === 'system' &&
+                    node.subtype === 'compact_boundary' &&
+                    typeof node.logicalParentUuid === 'string'
+                    ? node.logicalParentUuid
+                    : typeof node.parentUuid === 'string'
+                        ? node.parentUuid
+                        : null;
+        }
+    }
+    return null;
+}
 function ancestryUuids(entries, leafUuid) {
     const byUuid = new Map();
     for (const entry of entries) {
@@ -72,6 +115,9 @@ function selectAncestry(entries, leafUuid) {
         const uuid = entryUuid(entry);
         if (uuid) {
             return (active.has(uuid) ||
+                (entry.type === 'attachment' &&
+                    typeof entry.parentUuid === 'string' &&
+                    active.has(entry.parentUuid)) ||
                 (entry.type === 'user' &&
                     typeof entry.sourceToolAssistantUUID === 'string' &&
                     active.has(entry.sourceToolAssistantUUID)));

package/dist/core/context-budget.d.ts

@@ -5,6 +5,9 @@ export interface ContextBudgetOptions {
     /** Declares whether the configured window came from a provider capability so
      *  reports can distinguish provider-derived decisions from estimates. */
     windowSource?: 'capability' | 'estimate';
+    /** Receives at most one bounded diagnostic when provider accounting is
+     * malformed and the deterministic estimate fallback is used. */
+    onAccountingDiagnostic?: (message: string) => void;
 }
 export interface ContextBudgetEvaluateOptions {
     /** Most recent provider usage observation; a positive `contextWindow` is
@@ -18,6 +21,11 @@ export interface ContextBudgetEvaluateOptions {
 export type ContextBudgetSource = 'provider' | 'capability' | 'estimate';
 export interface ContextBudgetReport {
     estimatedTokens: number;
+    /** Total context occupancy used for overflow accounting: the actual provider
+     *  input/cache tokens at the observation watermark plus deterministic
+     *  estimated tokens added after that watermark. Without a usable watermark
+     *  this equals `estimatedTokens`. */
+    occupancyTokens: number;
     contextWindowTokens: number;
     reserveTokens: number;
     availableTokens: number;
@@ -37,10 +45,29 @@ export declare class ContextBudget {
     readonly reserveTokens: number;
     readonly windowSource: 'capability' | 'estimate';
     private observedUsage;
+    /** Actual provider input/cache tokens at the most recent usable observation;
+     *  the watermark that anchors later occupancy. */
+    private watermarkActualInputTokens;
+    /** Deterministic estimate of the request snapshot captured at observation
+     *  time; only growth beyond this baseline is added to the watermark. */
+    private watermarkBaselineEstimate;
+    private accountingDiagnosticEmitted;
+    private readonly onAccountingDiagnostic;
     constructor(options: ContextBudgetOptions);
-    observeUsage(usage: ModelUsage): void;
+    /** Record a completed provider request: `usage` carries the actual token
+     *  counts and `messages`/`tools` are the exact snapshot used for that
+     *  request. The snapshot's deterministic estimate becomes the watermark
+     *  baseline so later evaluations add only post-watermark growth. Malformed
+     *  usage is ignored (fail-open) and never throws; a valid `contextWindow`
+     *  still updates the effective window through `observedUsage`. */
+    observeUsage(usage: ModelUsage, messages?: readonly ModelMessage[], tools?: readonly ModelToolDefinition[]): void;
     effectiveContextWindow(usage?: ModelUsage): number;
     evaluate(messages: readonly ModelMessage[], tools?: readonly ModelToolDefinition[], options?: ContextBudgetEvaluateOptions): ContextBudgetReport;
+    /** Occupancy anchored at the actual input/cache watermark, adding only the
+     *  deterministic estimated growth past the observation baseline. Without a
+     *  usable watermark this is the plain estimate fallback. */
+    private anchoredOccupancyTokens;
+    private emitAccountingDiagnostic;
     assertFits(report: ContextBudgetReport): void;
     /** Returns the positive provider-reported context window, if any. */
     private providerContextWindow;

package/dist/core/context-budget.js

@@ -74,11 +74,38 @@ export function estimateModelRequestTokens(messages, tools = []) {
         estimateTextTokens(JSON.stringify(tool.inputSchema)), 0);
     return messageTokens + toolTokens;
 }
+/** Normalized provider input occupancy counting input and cache-read/creation
+ *  fields without output tokens. Returns `undefined` for malformed, negative,
+ *  or non-safe usage so accounting fails open. */
+function normalizedInputAndCacheTokens(usage) {
+    if (!Number.isSafeInteger(usage.inputTokens) ||
+        usage.inputTokens < 0 ||
+        (usage.cacheReadInputTokens !== undefined &&
+            (!Number.isSafeInteger(usage.cacheReadInputTokens) ||
+                usage.cacheReadInputTokens < 0)) ||
+        (usage.cacheCreationInputTokens !== undefined &&
+            (!Number.isSafeInteger(usage.cacheCreationInputTokens) ||
+                usage.cacheCreationInputTokens < 0))) {
+        return undefined;
+    }
+    const candidate = (usage.inputTokens ?? 0) +
+        (usage.cacheReadInputTokens ?? 0) +
+        (usage.cacheCreationInputTokens ?? 0);
+    return Number.isSafeInteger(candidate) ? candidate : undefined;
+}
 export class ContextBudget {
     contextWindowTokens;
     reserveTokens;
     windowSource;
     observedUsage;
+    /** Actual provider input/cache tokens at the most recent usable observation;
+     *  the watermark that anchors later occupancy. */
+    watermarkActualInputTokens;
+    /** Deterministic estimate of the request snapshot captured at observation
+     *  time; only growth beyond this baseline is added to the watermark. */
+    watermarkBaselineEstimate;
+    accountingDiagnosticEmitted = false;
+    onAccountingDiagnostic;
     constructor(options) {
         requirePositiveInteger(options.contextWindowTokens, 'Context window tokens');
         const defaultReserve = Math.min(8192, Math.max(1, Math.floor(options.contextWindowTokens / 10)));
@@ -90,15 +117,32 @@ export class ContextBudget {
         this.contextWindowTokens = options.contextWindowTokens;
         this.reserveTokens = reserveTokens;
         this.windowSource = options.windowSource ?? 'estimate';
+        this.onAccountingDiagnostic = options.onAccountingDiagnostic;
     }
-    observeUsage(usage) {
+    /** Record a completed provider request: `usage` carries the actual token
+     *  counts and `messages`/`tools` are the exact snapshot used for that
+     *  request. The snapshot's deterministic estimate becomes the watermark
+     *  baseline so later evaluations add only post-watermark growth. Malformed
+     *  usage is ignored (fail-open) and never throws; a valid `contextWindow`
+     *  still updates the effective window through `observedUsage`. */
+    observeUsage(usage, messages = [], tools = []) {
         this.observedUsage = usage;
+        const actualInputTokens = normalizedInputAndCacheTokens(usage);
+        if (actualInputTokens === undefined) {
+            this.emitAccountingDiagnostic();
+            return;
+        }
+        if (messages.length === 0 && tools.length === 0)
+            return;
+        this.watermarkActualInputTokens = actualInputTokens;
+        this.watermarkBaselineEstimate = estimateModelRequestTokens(messages, tools);
     }
     effectiveContextWindow(usage) {
         return this.providerContextWindow(usage) ?? this.contextWindowTokens;
     }
     evaluate(messages, tools = [], options = {}) {
         const estimatedTokens = estimateModelRequestTokens(messages, tools);
+        const occupancyTokens = this.anchoredOccupancyTokens(estimatedTokens);
         const providerWindow = this.providerContextWindow(options.lastUsage);
         const contextWindowTokens = providerWindow ?? this.contextWindowTokens;
         const outputTokens = options.outputTokens !== undefined &&
@@ -107,10 +151,11 @@ export class ContextBudget {
             ? options.outputTokens
             : 0;
         const availableTokens = Math.max(0, contextWindowTokens - this.reserveTokens);
-        const overflowTokens = Math.max(0, estimatedTokens + outputTokens - availableTokens);
+        const overflowTokens = Math.max(0, occupancyTokens + outputTokens - availableTokens);
         const shouldCompact = options.promptTooLong === true || overflowTokens > 0;
         return {
             estimatedTokens,
+            occupancyTokens,
             contextWindowTokens,
             reserveTokens: this.reserveTokens,
             availableTokens,
@@ -119,6 +164,29 @@ export class ContextBudget {
             source: providerWindow === undefined ? this.windowSource : 'provider',
         };
     }
+    /** Occupancy anchored at the actual input/cache watermark, adding only the
+     *  deterministic estimated growth past the observation baseline. Without a
+     *  usable watermark this is the plain estimate fallback. */
+    anchoredOccupancyTokens(estimatedTokens) {
+        if (this.watermarkActualInputTokens === undefined ||
+            this.watermarkBaselineEstimate === undefined) {
+            return estimatedTokens;
+        }
+        const growthAfterWatermark = Math.max(0, estimatedTokens - this.watermarkBaselineEstimate);
+        return this.watermarkActualInputTokens + growthAfterWatermark;
+    }
+    emitAccountingDiagnostic() {
+        if (this.accountingDiagnosticEmitted)
+            return;
+        this.accountingDiagnosticEmitted = true;
+        try {
+            this.onAccountingDiagnostic?.('Provider input usage was malformed; using deterministic context estimates.');
+        }
+        catch {
+            // Diagnostics are strictly best-effort. A broken sink must never turn
+            // fail-open accounting into a healthy-turn failure.
+        }
+    }
     assertFits(report) {
         if (report.shouldCompact)
             throw new ContextOverflowError(report);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",