@aragon-agent/cli 0.6.13 → 0.6.15

package/dist/compaction/wiring.js

@@ -1,40 +1,4 @@
-/**
- * `CompactionWiring` — the controller-side glue for context compaction
- * (context-auto-compaction §3.2.1 / §5.2).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
- *
- * CONSTRUCT BEFORE THE `Agent`, ATTACH AFTER IT (C-12 / D-19), and the split is
- * the whole reason this class has an `attach` method at all:
- *
- *   - The PORT has to be INSIDE the `Agent`'s constructor argument, because
- *     `AgentConfig.contextManager` has no setter and the loop reads it from the
- *     loop context.
- *   - The WIRING has to SUBSCRIBE to the `Agent`, because `compaction_end` is
- *     where the engine's `applied` verdict arrives and `agent_start` is what
- *     resets the per-run cap.
- *
- * `AgentController` cannot do both in one step: `new Agent({...})` runs before
- * every optional subsystem, precisely because `FastWiring`'s constructor
- * subscribes. So THIS CONSTRUCTOR MUST NOT SUBSCRIBE. A field assigned after the
- * `new Agent` call and spread into it conditionally produces a build where the
- * feature is registered, enabled, and SILENTLY ABSENT - the exact shape of
- * failure `controller.ts`'s `toolOutputs` comment documents.
- *
- * `manager()` returns a STABLE object for the controller's lifetime, whose two
- * methods delegate to a compactor that reads config LIVE - which is what lets
- * `/compact off`, `/compact threshold 0.8` and a settings-screen save take effect
- * mid-session without touching the `Agent`.
- *
- * DECLINED COMPACTIONS PRODUCE NO CLI EVENTS (quiet-noop §3.6). A `pressure`
- * compaction that changed nothing, called nothing and spent nothing never emits
- * `compaction_start`, so `onCompactorEvent` never opens a card and `settlePending`
- * finds neither a held record nor a skeleton to synthesize. CORE still emits its
- * own pair for every attempt, which is why `settlePending` still runs - it just
- * refreshes the snapshot and returns. `onCompactorEvent`'s `if (!this.open)`
- * guard is now unreachable for declines and stays for the abort race it was
- * written for.
- */
+import { shouldCompactAt } from './pressure.js';
 import { DEFAULT_RETRY_POLICY, estimatePromptTokens, initProviders, validateHistory, } from '@aragon-agent/core';
 import { getLogger } from '../logging/logger.js';
 import { mintRunId, writeArchive } from './archive.js';
@@ -126,6 +90,7 @@ export class CompactionWiring {
      * key, not an identity.
      */
     runId = mintRunId();
+    overflowNotified = false;
     constructor(deps) {
         this.deps = deps;
         this.enabled = deps.getConfig().compaction.enabled;
@@ -135,7 +100,10 @@ export class CompactionWiring {
                     getMessages: deps.getMessages,
                     getSystemPrompt: deps.getSystemPrompt,
                     getModelInfo: () => deps.getModelInfoFor(this.mainRef()),
-                    isWindowKnown: () => deps.isPricedModel(this.mainRef()),
+                    isWindowKnown: () => {
+                        const source = deps.getModelInfoFor(this.mainRef()).contextWindowSource;
+                        return source === undefined ? deps.isPricedModel(this.mainRef()) : source !== 'fallback';
+                    },
                     getWindowOverride: () => deps.getConfig().contextWindow,
                 });
         this.compactor = new Compactor({
@@ -164,7 +132,14 @@ export class CompactionWiring {
         // setter and `contextManager` is never reassigned; the LIVE switch is inside
         // `shouldCompact`, not in the identity of this object.
         this.port = {
-            shouldCompact: (probe) => this.enabled && this.compactor.shouldCompact(probe),
+            shouldCompact: (probe) => {
+                if (!this.enabled)
+                    return false;
+                const allowed = this.compactor.shouldCompact(probe);
+                if (probe.trigger === 'overflow' && !allowed)
+                    this.notifyOverflow();
+                return allowed;
+            },
             compact: (ctx) => this.compactor.compact(ctx),
         };
     }
@@ -190,6 +165,7 @@ export class CompactionWiring {
     }
     dispose() {
         this.compactor.abort();
+        this.compactor.clearPendingManual();
         this.unsubscribe?.();
         this.unsubscribe = null;
         this.listeners.clear();
@@ -202,6 +178,8 @@ export class CompactionWiring {
     }
     setEnabled(enabled) {
         this.enabled = enabled;
+        if (!enabled)
+            this.compactor.abort();
         // Turning it back on is the user overriding guard 4, which is the only way
         // out of a self-disable short of a restart.
         if (enabled)
@@ -212,6 +190,8 @@ export class CompactionWiring {
     onConfigChanged(enabled) {
         if (enabled !== undefined && enabled !== this.enabled) {
             this.enabled = enabled;
+            if (!enabled)
+                this.compactor.abort();
             if (enabled)
                 this.compactor.clearSelfDisable();
         }
@@ -241,8 +221,19 @@ export class CompactionWiring {
      * for such a session. A deep reset is idempotent, so both firing costs
      * nothing; deleting the controller's copy "to de-duplicate" reintroduces P0-2.
      */
-    onHistoryReplaced() {
-        this.meter.onHistoryReplaced();
+    onHistoryReplaced(identity) {
+        this.compactor.onHistoryReplaced(identity);
+    }
+    getIdentity() { return this.compactor.getIdentity(); }
+    notifyOverflow() {
+        const p = this.meter.current();
+        if (this.overflowNotified || !Number.isFinite(p.occupied) || p.occupied < 0 ||
+            !Number.isFinite(p.contextWindow) || p.contextWindow <= 0 ||
+            shouldCompactAt(p, this.deps.getConfig().compaction.threshold))
+            return;
+        this.overflowNotified = true;
+        this.deps.notify('warn', 'Context limit reached before the configured compaction threshold. ' +
+            'Use /compact or correct contextWindow.');
     }
     /**
      * The per-child manager factory, or `null` when children get none
@@ -266,7 +257,7 @@ export class CompactionWiring {
             // SINK (AC-H12). It is real money on the summarizer's price table, and a
             // background repair inside a background worker is exactly the spend a
             // user would otherwise never see.
-            onUsage: (usage) => this.emit({ type: 'usage', usage }),
+            onUsage: (usage, billing) => this.emit({ type: 'usage', usage, ...billing }),
         });
     }
     // -----------------------------------------------------------------------
@@ -281,28 +272,13 @@ export class CompactionWiring {
     clearPendingManual() {
         this.compactor.clearPendingManual();
     }
-    /**
-     * The IDLE `/compact` path (§4.4 / D-25).
-     *
-     * IT VALIDATES BEFORE IT SPLICES, AND THAT IS NOT OPTIONAL (P1-7). When the
-     * agent is idle there is no loop, so §3.3 step 5 does not run — and the only
-     * way to replace the history is `Agent.replaceMessages`, which validates
-     * nothing. D-4 declares that gate unbypassable and R-2 calls an invalid splice
-     * the worst possible outcome, so this path mirrors the engine's steps 3-5
-     * exactly, INCLUDING the failure vocabulary: the card, the log and
-     * `/compact status` cannot tell the two paths apart.
-     *
-     * No watchdog handling is needed — `runLoopWithLifecycle`'s `finally` already
-     * called `watchdog.stop()`, so nothing is armed while idle.
-     *
-     * ITS CALLER MUST ADOPT `messages` — THE ARCHIVE IS ALREADY WRITTEN BY THE
-     * TIME THIS RETURNS (hardening RV-7). This path settles `applied: true` here,
-     * one statement before the caller splices, so the "never archive a live
-     * history" rule holds only because that caller applies unconditionally. That is
-     * a fact about one call site rather than an invariant, which is why it is
-     * written down where it can be checked.
-     */
+    /** Prepare, validate and synchronously adopt before publishing a successful verdict. */
     async compactNow(args) {
+        if (!this.enabled)
+            return { ok: false, reason: 'disabled' };
+        if (this.compactor.sessionTotals().inFlight)
+            return { ok: false, reason: 'already_running' };
+        this.compactor.onRunStart();
         this.compactor.queueManual(args.instructions);
         // BOTH SIDES FROM CORE'S OWN ESTIMATOR, exactly as the in-loop path gets them
         // from `compaction_end` (§5.1). There is no engine event here to supply them,
@@ -339,6 +315,19 @@ export class CompactionWiring {
             this.settlePending({ applied: false, reason, tokensBefore, tokensAfter: tokensBefore });
             return { ok: false, reason };
         }
+        if (args.signal.aborted || args.isCurrent?.() === false || !args.adopt) {
+            const reason = args.signal.aborted ? 'aborted' : 'stale_history';
+            this.settlePending({ applied: false, reason, tokensBefore, tokensAfter: tokensBefore });
+            return { ok: false, reason };
+        }
+        try {
+            args.adopt(outcome.messages);
+        }
+        catch (error) {
+            const reason = `adoption_failed: ${error instanceof Error ? error.message : String(error)}`;
+            this.settlePending({ applied: false, reason, tokensBefore, tokensAfter: tokensBefore });
+            return { ok: false, reason };
+        }
         this.settlePending({
             applied: true,
             tokensBefore,
@@ -384,6 +373,7 @@ export class CompactionWiring {
             ...(totals.declined > 0 ? { declined: totals.declined } : {}),
             tokensReclaimed: totals.tokensReclaimed,
             usage: totals.usage,
+            costUsd: totals.costUsd,
             pricingUnknown: totals.pricingUnknown,
             inFlight: totals.inFlight,
             selfDisabled: totals.selfDisabled,
@@ -457,9 +447,13 @@ export class CompactionWiring {
     onAgentEvent(event) {
         if (event.type === 'agent_start') {
             this.compactor.onRunStart();
+            this.overflowNotified = false;
             return;
         }
+        if (event.type === 'agent_end')
+            this.compactor.onRunEnd();
         if (event.type === 'turn_end') {
+            this.meter.onTurnEnd(event.usage);
             // THE MEASUREMENT IS THE METER'S (context-usage-gauge-accuracy §3.3.4). It
             // subscribes to `turn_end` on the same stream and recomputes the offset,
             // the prefix length and the pressure there; the two calls that used to
@@ -498,6 +492,7 @@ export class CompactionWiring {
         // engine cannot report `true` without a `replace` outcome, which means the
         // compactor's own record already exists — so its zeroed counts are never
         // rendered.
+        this.compactor.settleOperation(verdict);
         const record = this.pending ?? this.skeletonRecord();
         this.pending = null;
         this.open = null;
@@ -530,7 +525,6 @@ export class CompactionWiring {
             mode: verdict.applied ? record.mode : 'none',
         };
         if (verdict.applied) {
-            this.compactor.recordApplied(settled.tokensBefore, settled.tokensAfter);
             // SITE 1 OF THE FOUR INVALIDATION SITES (hardening §3.2.3), and THE LOAD-
             // BEARING LINE OF THE P0-1 FIX (context-usage-gauge-accuracy I-9).
             //
@@ -562,9 +556,8 @@ export class CompactionWiring {
      * archive a history that is still live" - and the two paths reach that verdict
      * at different moments relative to the splice. In loop, the ENGINE decides
      * after `validateHistory`, so this runs AFTER adoption. On the manual path the
-     * WIRING decides and `compactNow`'s caller adopts on the next statement, so
-     * this runs BEFORE adoption; `compactNow`'s doc comment carries that obligation
-     * for its one caller (RV-7).
+     * WIRING invokes the host adoption callback before settling, so both paths
+     * archive only histories that have actually been replaced.
      *
      * BEST-EFFORT AND SYNCHRONOUS-BUT-GUARDED. `writeArchive` never throws and
      * logs its own failure; a failed archive never affects the compaction, and it

package/dist/config/load.d.ts

@@ -241,7 +241,9 @@ export interface CliFlags {
  * Resolve the effective config by merging all layers, then derive the runtime
  * (non-persisted) fields and enforce the timeout invariant.
  */
-export declare function loadConfig(flags?: CliFlags): CliConfig;
+export declare function loadConfig(flags?: CliFlags, options?: {
+    interactive?: boolean;
+}): CliConfig;
 /**
  * Build the `getApiKey(providerId)` resolver the core `Agent` consumes.
  * The one-shot `--api-key` override wins, but only for the active provider.

package/dist/config/load.js

@@ -16,7 +16,7 @@ import { setEntryRetain } from '../agent/entry-limits.js';
 import { readSubmitCount } from './ui-state.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret, registerSecretsFrom } from '../logging/secret-registry.js';
-import { detectCapabilities } from '../ui/capabilities.js';
+import { detectCapabilities, resolveTuiCapabilities } from '../ui/capabilities.js';
 /** Interpret a boolean-ish env value (`1/true/on/yes`) as `true`. */
 function envFlagTrue(value) {
     if (!value)
@@ -436,7 +436,7 @@ function resolveContextWindow(env, file) {
  * Resolve the effective config by merging all layers, then derive the runtime
  * (non-persisted) fields and enforce the timeout invariant.
  */
-export function loadConfig(flags = {}) {
+export function loadConfig(flags = {}, options = {}) {
     const cwd = flags.cwd ? flags.cwd : process.cwd();
     // `.env` must be loaded before reading env overrides.
     loadDotenv(cwd);
@@ -519,13 +519,17 @@ export function loadConfig(flags = {}) {
     // registering twice costs a `Set.add`, missing once costs a credential.
     registerSecretsFrom(apiKeys);
     registerSecret(flags.apiKey);
-    const color = flags.color !== undefined ? flags.color : !process.env.NO_COLOR;
+    const caps = options.interactive
+        ? resolveTuiCapabilities(process.env, flags.color)
+        : detectCapabilities(process.env, process.stdout);
+    const color = options.interactive
+        ? caps.colorLevel !== 0
+        : flags.color !== undefined ? flags.color : !process.env.NO_COLOR;
     // `--no-color` implies calmer chrome; env / file may also opt in explicitly.
     const reducedMotion = envFlagTrue(process.env.ARAGON_REDUCED_MOTION) ||
         (file.reducedMotion ?? DEFAULT_CONFIG.reducedMotion) ||
         !color;
     // Detect terminal capabilities once; force monochrome when color is disabled.
-    const caps = detectCapabilities(process.env, process.stdout);
     const colorLevel = color ? caps.colorLevel : 0;
     // No flag and no env var: a privacy switch you set once, not a per-run knob.
     const historyEnabled = file.historyEnabled ?? DEFAULT_CONFIG.historyEnabled;

package/dist/config/schema.d.ts

@@ -577,7 +577,7 @@ export interface CompactionConfig {
      * SESSION'S OWN MODEL, and the first compaction is a ~30 k-token call on it.
      */
     useFastTier: boolean;
-    /** What happens when summarization fails outright. See §3.7 rungs 3 / 4. */
+    /** Legacy truncate remains readable; all failures now preserve history. */
     onFailure: CompactionFailureMode;
     /**
      * Give `task` children their own compaction
@@ -1097,9 +1097,9 @@ export interface CliConfig {
     cwd: string;
     /** Whether ANSI color is enabled. */
     color: boolean;
-    /** Detected terminal color depth (0 none · 1 16 · 2 256 · 3 truecolor). */
+    /** Resolved color depth: TUI policy or non-interactive terminal detection. */
     colorLevel?: 0 | 1 | 2 | 3;
-    /** Detected Unicode support (box/round glyphs & spinners). */
+    /** TUI always enables Unicode; non-interactive output uses detection. */
     unicode?: boolean;
     /** One-shot `--api-key` override; applies to the active provider only. */
     apiKeyOverride?: string;

package/dist/config/schema.js

@@ -744,7 +744,7 @@ export const DEFAULT_COMPACTION_CONFIG = {
     warnThreshold: 0.75,
     keepRecentTurns: 4,
     useFastTier: true,
-    onFailure: 'truncate',
+    onFailure: 'stop',
     subagents: true,
     archive: true,
 };

package/dist/exec/events.d.ts

@@ -274,6 +274,14 @@ export interface ExecFastTierEvent {
  * it. What a wrapper does need is the SHAPE of what happened, which is here.
  */
 export interface ExecCompactionEvent {
+    decision?: {
+        occupied: number;
+        contextWindow: number;
+        threshold: number;
+        source: 'usage' | 'estimate';
+        deltaTokens: number;
+    };
+    memoryVersion?: 2;
     type: 'compaction';
     sessionId: string;
     turn: number;

package/dist/exec/index.js

@@ -111,7 +111,7 @@ async function execute(input) {
         now,
     });
     if (plan.saved) {
-        controller.replaceMessages(plan.saved.messages);
+        controller.replaceMessages(plan.saved.messages, plan.saved.compactionIdentity);
         controller.restoreTodos(plan.saved.todos);
     }
     const config = controller.getConfig();
@@ -187,7 +187,7 @@ async function execute(input) {
             outputTokens: stats.usage.outputTokens,
             totalTokens: stats.usage.inputTokens + stats.usage.outputTokens,
         },
-        cost: buildCost(controller, stats.usage),
+        cost: buildCost(controller, stats.usage, stats.compactionBilling),
         model: { provider: config.provider, id: config.model },
         todos: todo ? { total: todo.total, done: todo.doneCount } : null,
         error: stats.errorCode && stats.errorMessage
@@ -253,17 +253,24 @@ async function drive(input, controller, runner) {
 function withPermissionMode(flags, mode) {
     return mode === 'plan' ? { ...flags, plan: true } : flags;
 }
-function buildCost(controller, usage) {
+function buildCost(controller, usage, compaction) {
     const config = controller.getConfig();
-    const known = controller.isPricedModel({
+    const known = !compaction?.pricingUnknown && controller.isPricedModel({
         providerId: config.provider,
         modelId: config.model,
     });
+    const mainUsage = {
+        inputTokens: usage.inputTokens - (compaction?.usage.inputTokens ?? 0),
+        outputTokens: usage.outputTokens - (compaction?.usage.outputTokens ?? 0),
+        cacheReadTokens: (usage.cacheReadTokens ?? 0) - (compaction?.usage.cacheReadTokens ?? 0),
+        cacheWriteTokens: (usage.cacheWriteTokens ?? 0) - (compaction?.usage.cacheWriteTokens ?? 0),
+    };
     // `amount` is `0` when the price is unknown, mirroring the fast tier's rule
     // that a feature which looks free while it is spending money is worse than one
     // that admits it does not know.
     return {
-        amount: known ? computeCost(usage, controller.getModelInfo().cost) : 0,
+        amount: known ? computeCost(mainUsage, controller.getModelInfo().cost) +
+            (compaction?.costUsd ?? 0) : 0,
         currency: 'USD',
         known,
     };
@@ -460,7 +467,7 @@ function persist(plan, controller, turns, usage, cli, at) {
                     modelId: config.model,
                     ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
                 },
-                messages: controller.getMessages(),
+                ...(controller.getSessionSnapshot?.() ?? { messages: controller.getMessages() }),
                 entries: [],
                 todos: controller.getTodoSnapshot?.()?.items ?? [],
             },

package/dist/exec/runner.d.ts

@@ -72,7 +72,13 @@ export interface ExecRunnerOptions {
     /** Turns already spent by earlier invocations of a resumed session. */
     priorTurns?: number;
 }
+export interface ExecCompactionBilling {
+    usage: TokenUsage;
+    costUsd: number;
+    pricingUnknown: boolean;
+}
 export interface ExecRunStats {
+    compactionBilling?: ExecCompactionBilling;
     turns: number;
     usage: TokenUsage;
     lastAssistantText: string;
@@ -93,6 +99,7 @@ export declare class ExecRunner {
     private unsubscribers;
     private turns;
     private readonly usage;
+    private compactionBilling;
     private lastAssistantText;
     private errored;
     private sawTurnEnd;
@@ -143,6 +150,7 @@ export declare class ExecRunner {
      * the two faces cannot drift about what "unfinished" means.
      */
     run(source: ExecPromptSource): Promise<void>;
+    private onCompactionUsage;
     private requestSeq;
     private requestHadError;
     private isRequestCancelled;

package/dist/exec/runner.js

@@ -46,6 +46,7 @@ export class ExecRunner {
     unsubscribers = [];
     turns = 0;
     usage = { inputTokens: 0, outputTokens: 0 };
+    compactionBilling;
     lastAssistantText = '';
     errored = false;
     sawTurnEnd = false;
@@ -175,8 +176,7 @@ export class ExecRunner {
         // wrapper gets.
         const compaction = controller.subscribeCompaction?.((event) => {
             if (event.type === 'usage') {
-                this.usage.inputTokens += event.usage.inputTokens;
-                this.usage.outputTokens += event.usage.outputTokens;
+                this.onCompactionUsage(event);
                 return;
             }
             if (event.type === 'compaction_start') {
@@ -208,6 +208,8 @@ export class ExecRunner {
                 tokensBefore: r.tokensBefore,
                 tokensAfter: r.tokensAfter,
                 ...(r.tailRelief ? { tailRelief: r.tailRelief } : {}),
+                ...(r.decision ? { decision: r.decision } : {}),
+                ...(r.memoryVersion ? { memoryVersion: r.memoryVersion } : {}),
                 durationMs: r.durationMs,
             });
         });
@@ -246,6 +248,9 @@ export class ExecRunner {
         return {
             turns: this.turns,
             usage: { ...this.usage },
+            ...(this.compactionBilling ? { compactionBilling: {
+                    ...this.compactionBilling, usage: { ...this.compactionBilling.usage },
+                } } : {}),
             lastAssistantText: this.lastAssistantText,
             errored: this.errored,
             stopReason: this.stopReason,
@@ -322,6 +327,25 @@ export class ExecRunner {
             }
         }
     }
+    onCompactionUsage(event) {
+        const usage = event.usage;
+        this.usage.inputTokens += usage.inputTokens;
+        this.usage.outputTokens += usage.outputTokens;
+        for (const key of ['cacheReadTokens', 'cacheWriteTokens']) {
+            if (usage[key] !== undefined)
+                this.usage[key] = (this.usage[key] ?? 0) + usage[key];
+        }
+        if (event.costUsd === undefined && event.pricingUnknown === undefined)
+            return;
+        const billing = this.compactionBilling ??= { costUsd: 0, pricingUnknown: false,
+            usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 } };
+        billing.costUsd += event.costUsd ?? 0;
+        billing.pricingUnknown ||= event.pricingUnknown === true;
+        billing.usage.inputTokens += usage.inputTokens;
+        billing.usage.outputTokens += usage.outputTokens;
+        billing.usage.cacheReadTokens += usage.cacheReadTokens ?? 0;
+        billing.usage.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+    }
     requestSeq = 0;
     requestHadError = false;
     isRequestCancelled() {

package/dist/session/persist.d.ts

@@ -8,6 +8,7 @@
 import type { Message, ModelRef } from '@aragon-agent/core';
 import type { Entry } from '../agent/reducer.js';
 import type { TodoItem } from '../todo/types.js';
+import { type CompactionIdentity } from '../compaction/memory-identity.js';
 /**
  * Bookkeeping `aragon exec` attaches to the sessions it owns
  * (cli-integration-surface §5.2).
@@ -41,6 +42,7 @@ export interface SavedSession {
     savedAt: number;
     model?: ModelRef;
     messages: Message[];
+    compactionIdentity?: CompactionIdentity;
     entries: Entry[];
     /**
      * The live todo list at save time (todo-plan-execution §3.13).
@@ -79,6 +81,7 @@ export declare function resolveSessionPath(nameOrPath: string | undefined, cwd:
 export declare function saveSession(filePath: string, data: {
     model: ModelRef;
     messages: Message[];
+    compactionIdentity?: CompactionIdentity;
     entries: Entry[];
     todos: TodoItem[];
     meta?: SessionMeta;

package/dist/session/persist.js

@@ -9,6 +9,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { getSessionsDir } from '../config/store.js';
 import { validateSession } from './validate-session.js';
+import { validateCompactionIdentity, verifyCompactionIdentity, } from '../compaction/memory-identity.js';
+import { getLogger } from '../logging/logger.js';
 const SESSION_VERSION = 1;
 /** Resolve a `/save` target: absolute/relative path, or a name in the data dir. */
 export function resolveSessionPath(nameOrPath, cwd) {
@@ -92,6 +94,12 @@ function stripServiceTail(entries) {
  * payload with no such key and a file byte-identical to today's.
  */
 export function saveSession(filePath, data) {
+    if (data.compactionIdentity) {
+        validateCompactionIdentity(data.compactionIdentity);
+        if (!verifyCompactionIdentity(data.messages, data.compactionIdentity)) {
+            getLogger().debug('agent', 'invalid_compaction_session_identity');
+        }
+    }
     const dir = dirname(filePath);
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
@@ -100,6 +108,7 @@ export function saveSession(filePath, data) {
         savedAt: Date.now(),
         model: data.model,
         messages: data.messages,
+        ...(data.compactionIdentity ? { compactionIdentity: data.compactionIdentity } : {}),
         entries: stripServiceTail(stripLiveToolOutput(data.entries)),
         todos: data.todos,
         ...(data.meta ? { meta: data.meta } : {}),

package/dist/session/store.js

@@ -159,6 +159,8 @@ export function writeSession(input) {
     saveSession(path, {
         model: input.session.model,
         messages: input.session.messages,
+        ...(input.session.compactionIdentity
+            ? { compactionIdentity: input.session.compactionIdentity } : {}),
         entries: input.session.entries,
         todos: input.session.todos ?? [],
         meta: input.meta,

package/dist/session/validate-session.js

@@ -1,6 +1,8 @@
 import { isAdapterProvider } from '../config/schema.js';
 import { normalizeTodos } from '../todo/normalize.js';
 import { TODO_LIMITS } from '../todo/limits.js';
+import { validateCompactionIdentity } from '../compaction/memory-identity.js';
+import { MemoryError } from '../compaction/memory.js';
 function fail(path, expected) {
     throw new Error(`Invalid session file: ${path} must be ${expected}.`);
 }
@@ -26,6 +28,25 @@ const boolean = (value, path) => {
     if (typeof value !== 'boolean')
         fail(path, 'a boolean');
 };
+const nonnegative = (value, path) => {
+    number(value, path);
+    if (value < 0)
+        fail(path, 'non-negative');
+};
+const positive = (value, path) => {
+    number(value, path);
+    if (value <= 0)
+        fail(path, 'positive');
+};
+const threshold = (value, path) => {
+    number(value, path);
+    if (value < 0.5 || value > 0.95)
+        fail(path, 'between 0.5 and 0.95');
+};
+const memoryVersion = (value, path) => {
+    if (value !== 2)
+        fail(path, '2');
+};
 const object = (value, path) => { record(value, path); };
 function optional(check) {
     return (value, path) => { if (value !== undefined)
@@ -149,6 +170,9 @@ const ENTRY_FIELDS = {
         text: optional(string), detail: optional(string), turn: number,
         durationMs: optional(number), live: boolean },
     compaction: {
+        decision: optional(shape({ occupied: nonnegative, contextWindow: positive,
+            threshold, source: enumeration('usage', 'estimate'), deltaTokens: nonnegative })),
+        memoryVersion: optional(memoryVersion),
         index: number, trigger: enumeration('pressure', 'overflow', 'manual'),
         mode: enumeration('summarized', 'truncated', 'relieved', 'none'), applied: boolean,
         reason: optional(string), messagesBefore: number, messagesAfter: number,
@@ -198,6 +222,16 @@ export function validateSession(value) {
     validateEntries(source.entries);
     if (source.model !== undefined)
         validateModel(source.model);
+    if (source.compactionIdentity !== undefined) {
+        try {
+            validateCompactionIdentity(source.compactionIdentity);
+        }
+        catch (error) {
+            if (!(error instanceof MemoryError))
+                throw error;
+            fail('compactionIdentity', 'a valid adopted-memory identity');
+        }
+    }
     // Missing fields remain missing in old files, including exec metadata.
     const prepared = { ...source };
     if (source.todos !== undefined) {

package/dist/team/subagent.js

@@ -331,6 +331,14 @@ export function createSubagent(spec, deps, hooks) {
                 }
                 break;
             }
+            case 'compaction_end':
+                contextManager?.onCompactionEnd({
+                    applied: event.applied,
+                    ...(event.reason !== undefined ? { reason: event.reason } : {}),
+                    tokensBefore: event.estimatedTokensBefore,
+                    tokensAfter: event.estimatedTokensAfter,
+                });
+                break;
             case 'tool_execution_start':
                 run.phase = event.toolName === 'team_wait' ? 'waiting' : 'tool';
                 run.lastTool = event.toolName;