praxis-agent 0.24.1 → 0.26.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.d.ts

@@ -244,6 +244,13 @@ export declare class ClaudeSessionService {
     private sessionNameEntries;
     private hasSessionName;
     private sessionName;
+    /** Conservative selective-preservation seam for manual compact: when the
+     *  durable session memory watermark matches an active entry, summarize the
+     *  last good memory artifact plus the post-watermark branch and retain a
+     *  recent suffix. Returns null to fall back to the existing full-compaction
+     *  behavior (missing/invalid watermark, empty projection, or oversized
+     *  projection). */
+    private selectMemoryPreservedCompact;
     private lastMessageUuid;
     private promptIdForToolCall;
     private assistantIdForToolCall;

package/dist/application/session-service.js

@@ -13,7 +13,7 @@ import { ClaudeFileHistory } from '../compatibility/claude/file-history.js';
 import { getClaudePrLink } from '../compatibility/claude/pr-links.js';
 import { getClaudeAgentSetting, getClaudeLastPrompt, projectClaudeDisplayTranscript, projectClaudeModelMessages, } from '../compatibility/claude/projection.js';
 import { selectClaudeSchemaAdapter, } from '../compatibility/claude/schema.js';
-import { findUnresolvedClaudeToolCalls } from '../compatibility/claude/tool-links.js';
+import { findUnresolvedClaudeToolCalls, getClaudeContentBlocks, } from '../compatibility/claude/tool-links.js';
 import { createClaudeAgentSettingEntry, createClaudeHookAttachmentEntries, createClaudeLastPromptEntry, createClaudeRuleAttachmentEntry, translateProviderEvents, } from '../compatibility/claude/translation.js';
 import { AgentRunCancelledError, AgentRuntime, } from '../core/runtime.js';
 import { BackgroundTaskRuntime, } from './background-task-runtime.js';
@@ -302,6 +302,114 @@ Update the durable session memory from the conversation so far. Preserve:
 Omit transient chatter, credentials, secrets, or personal data.
 
 Return ONLY an updated Markdown document that becomes the session's durable memory. Do not call tools. Do not include any prose outside the Markdown document.`;
+/** Memory-anchored manual compact keeps a recent suffix of at least five
+ *  text-bearing messages and approximately ten thousand tokens when the active
+ *  branch can provide them. Larger suffixes stay conservative. */
+const MEMORY_COMPACT_MIN_SUFFIX_MESSAGES = 5;
+const MEMORY_COMPACT_MIN_SUFFIX_TOKENS = 10_000;
+/** Above this estimated compactor projection the selective path falls back to
+ *  the existing full-compaction behavior instead of building an oversized
+ *  projection. */
+const MEMORY_COMPACT_MAX_PROJECTION_TOKENS = 40_000;
+function isTextBearingClaudeEntry(entry) {
+    if (typeof entry.message !== 'object' ||
+        entry.message === null ||
+        Array.isArray(entry.message)) {
+        return false;
+    }
+    const message = entry.message;
+    const content = message.content;
+    if (message.role === 'user') {
+        if (typeof content === 'string')
+            return content.trim().length > 0;
+        if (!Array.isArray(content))
+            return false;
+        return content.some((block) => typeof block === 'object' &&
+            block !== null &&
+            (block.type === 'text' ||
+                block.type === 'tool_result' ||
+                block.type === 'image' ||
+                block.type === 'document'));
+    }
+    if (message.role === 'assistant') {
+        if (!Array.isArray(content))
+            return false;
+        return content.some((block) => typeof block === 'object' &&
+            block !== null &&
+            (block.type === 'text' ||
+                block.type === 'tool_use' ||
+                block.type === 'thinking'));
+    }
+    return false;
+}
+function claudeToolResultIds(entry) {
+    const ids = new Set();
+    if (entry.type !== 'user')
+        return ids;
+    for (const block of getClaudeContentBlocks(entry)) {
+        if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+            ids.add(block.tool_use_id);
+        }
+    }
+    return ids;
+}
+function claudeAssistantHasToolUse(entry, ids) {
+    if (entry.type !== 'assistant')
+        return false;
+    return getClaudeContentBlocks(entry).some((block) => block.type === 'tool_use' &&
+        typeof block.id === 'string' &&
+        ids.has(block.id));
+}
+/** Pulls the preserved-suffix boundary backward so a tool_use assistant entry
+ *  and its tool_result user entry stay siblings: the suffix never opens with an
+ *  orphaned tool_result and the compacted input never ends with a dangling
+ *  tool_use. Same-response thinking/tool blocks live in one assistant entry,
+ *  so entry-level cutting never splits them. */
+function completeClaudeToolPairBoundary(activeEntries, startIndex) {
+    let boundary = startIndex;
+    while (boundary < activeEntries.length) {
+        const entry = activeEntries[boundary];
+        if (!entry)
+            break;
+        const ids = claudeToolResultIds(entry);
+        if (ids.size === 0)
+            break;
+        let extended = false;
+        for (let index = boundary - 1; index >= 0; index -= 1) {
+            const candidate = activeEntries[index];
+            if (candidate && claudeAssistantHasToolUse(candidate, ids)) {
+                boundary = index;
+                extended = true;
+                break;
+            }
+        }
+        if (!extended)
+            break;
+    }
+    return boundary;
+}
+/** Walks back from the active tail to the inclusive start of the recent suffix
+ *  retained verbatim, then completes sibling adjacency at the boundary. */
+function memoryPreservedSuffixStart(activeEntries) {
+    let start = activeEntries.length;
+    let textBearing = 0;
+    let estimatedTokens = 0;
+    for (let index = activeEntries.length - 1; index >= 0; index -= 1) {
+        const entry = activeEntries[index];
+        if (!entry)
+            continue;
+        start = index;
+        if (!isTextBearingClaudeEntry(entry))
+            continue;
+        textBearing += 1;
+        estimatedTokens += estimateModelRequestTokens(projectClaudeModelMessages([entry]));
+        if (textBearing >= MEMORY_COMPACT_MIN_SUFFIX_MESSAGES &&
+            (estimatedTokens >= MEMORY_COMPACT_MIN_SUFFIX_TOKENS || index === 0)) {
+            break;
+        }
+    }
+    return completeClaudeToolPairBoundary(activeEntries, start);
+}
 function validPromptSuggestion(value) {
     const suggestion = value.trim();
     if (!suggestion)
@@ -871,7 +979,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');
         }
@@ -1464,6 +1572,7 @@ export class ClaudeSessionService {
             let selectedEntries = activeEntries;
             let logicalParentUuid = this.lastMessageUuid(activeEntries);
             let preservedEntries = [];
+            let memoryMessage;
             if (selection) {
                 const targetIndex = activeEntries.findIndex((entry) => entry.uuid === selection.messageId);
                 if (targetIndex < 0) {
@@ -1486,8 +1595,18 @@ export class ClaudeSessionService {
                             : this.lastMessageUuid(selectedEntries);
                 }
             }
+            else {
+                const memorySelection = await this.selectMemoryPreservedCompact(sessionId, activeEntries);
+                if (memorySelection) {
+                    selectedEntries = [...memorySelection.compactedEntries];
+                    preservedEntries = [...memorySelection.preservedEntries];
+                    logicalParentUuid = memorySelection.logicalParentUuid;
+                    memoryMessage = memorySelection.memoryMessage;
+                }
+            }
             const selectedMessages = projectClaudeModelMessages(selectedEntries);
             const messages = [
+                ...(memoryMessage === undefined ? [] : [memoryMessage]),
                 ...selectedMessages,
                 ...(selection?.context
                     ? [
@@ -1588,7 +1707,11 @@ export class ClaudeSessionService {
                         },
                         preservedUuids: preservedEntries.flatMap((entry) => typeof entry.uuid === 'string' ? [entry.uuid] : []),
                     }
-                    : {}),
+                    : memoryMessage
+                        ? {
+                            preservedUuids: preservedEntries.flatMap((entry) => typeof entry.uuid === 'string' ? [entry.uuid] : []),
+                        }
+                        : {}),
                 createUuid: () => uuids.shift() ?? randomUUID(),
             });
             const appendResult = await lease.appendMany(snapshot.tail, entries);
@@ -3051,7 +3174,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 +3271,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;
@@ -3276,6 +3402,59 @@ export class ClaudeSessionService {
             return agentName;
         return null;
     }
+    /** Conservative selective-preservation seam for manual compact: when the
+     *  durable session memory watermark matches an active entry, summarize the
+     *  last good memory artifact plus the post-watermark branch and retain a
+     *  recent suffix. Returns null to fall back to the existing full-compaction
+     *  behavior (missing/invalid watermark, empty projection, or oversized
+     *  projection). */
+    async selectMemoryPreservedCompact(sessionId, activeEntries) {
+        const controller = this.sessionMemoryController(sessionId);
+        if (controller === null)
+            return null;
+        let watermark = null;
+        let memorySummary = '';
+        try {
+            const [state, summary] = await Promise.all([
+                controller.state(),
+                controller.summary(),
+            ]);
+            watermark = state.lastSummarizedMessageId;
+            memorySummary = summary;
+        }
+        catch {
+            return null;
+        }
+        if (watermark === null || watermark.length === 0)
+            return null;
+        if (memorySummary.trim().length === 0)
+            return null;
+        const watermarkIndex = activeEntries.findIndex((entry) => entry.uuid === watermark);
+        if (watermarkIndex < 0)
+            return null;
+        const suffixStart = memoryPreservedSuffixStart(activeEntries);
+        if (suffixStart <= 0 || suffixStart <= watermarkIndex + 1)
+            return null;
+        const compactedEntries = activeEntries.slice(watermarkIndex + 1, suffixStart);
+        const preservedEntries = activeEntries.slice(suffixStart);
+        const selectedMessages = projectClaudeModelMessages(compactedEntries);
+        if (selectedMessages.length === 0)
+            return null;
+        const memoryMessage = { role: 'user', content: memorySummary };
+        if (estimateModelRequestTokens([memoryMessage, ...selectedMessages]) >
+            MEMORY_COMPACT_MAX_PROJECTION_TOKENS) {
+            return null;
+        }
+        const logicalParentUuid = this.lastMessageUuid(activeEntries.slice(0, suffixStart));
+        if (logicalParentUuid === null)
+            return null;
+        return {
+            compactedEntries,
+            preservedEntries,
+            memoryMessage,
+            logicalParentUuid,
+        };
+    }
     lastMessageUuid(entries) {
         for (let index = entries.length - 1; index >= 0; index -= 1) {
             const entry = entries[index];
@@ -3852,6 +4031,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.26.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",