@aragon-agent/core 0.2.51 → 0.2.52

package/dist/engine/compaction.d.ts

@@ -21,6 +21,16 @@ export interface CompactionPlan {
     cutIndex: number;
     droppedMessages: number;
     retainedTurns: number;
+    /**
+     * Set when this plan exists only because `retainMessages` allowed the turn
+     * requirement to be relaxed.
+     *
+     * THE HOST MUST ANNOUNCE IT. A relaxed cut keeps fewer user turns than
+     * `keepRecentTurns` asked for, and the recent turns are the part of a history a
+     * user cares most about keeping word for word - so a compaction that quietly
+     * traded that away would be lying by omission about its own result.
+     */
+    keepRelaxed?: boolean;
 }
 export type HistoryCheck = {
     ok: true;
@@ -63,6 +73,32 @@ export interface PlanCompactionOptions {
      * to save a parameter.
      */
     protectedPrefix?: number;
+    /**
+     * The smallest tail - in MESSAGES - a second planning pass may settle for.
+     *
+     * OPTIONAL, AND THAT IS THE WHOLE CONTRACT (context-compaction-never-fires B).
+     * Without it `planCompaction` behaves exactly as it always has, which is what
+     * keeps the four existing assertions in `compaction.test.ts` ({keep: 4} null,
+     * {keep: 99} null, the `protectedPrefix` exit, and the idempotence guard) true
+     * without editing a line of them. The relaxation is a NEW MODE a host opts into,
+     * not a change to `keepRecentTurns`'s meaning.
+     *
+     * WHY IT IS NEEDED AT ALL. `keepRecentTurns` counts `user` messages, and this
+     * package's dominant session shape is one user prompt followed by a hundred
+     * turns of tool calls. Such a history retains 0 user turns behind any cut, so it
+     * has no legal plan under any `keepRecentTurns >= 1` - 107 of 119 long sessions
+     * on the reporting machine. Passing this field says "a cut with a genuinely
+     * useful tail beats no cut at all".
+     *
+     * WHY IT IS MESSAGES AND NOT TURNS. The tail has to remain a usable continuation
+     * window: the number is a structural bound (tens of messages), chosen by the
+     * host, not a policy about turns.
+     *
+     * THE EXIT CONDITION IS UNCHANGED. `cutIndex <= protectedPrefix` still returns
+     * `null` in both passes, so an already-compacted history with nothing new is
+     * still refused (the idempotence guard) and the anchor is still never dropped.
+     */
+    retainMessages?: number;
 }
 /**
  * The largest safe cut that still leaves at least `keepRecentTurns` complete
@@ -71,6 +107,15 @@ export interface PlanCompactionOptions {
  * `null` — rather than a zero-length head — is what lets §3.8 turn "the recent
  * turns alone exceed the threshold" into a bounded, loud outcome instead of a
  * retry loop against a paid API.
+ *
+ * TWO PASSES, AND THE SECOND ONE IS OPT-IN (`opts.retainMessages`). The first pass
+ * is unchanged: the largest safe cut that leaves `keepRecentTurns` user turns
+ * behind it. Only when that pass finds nothing AND the caller supplied a
+ * `retainMessages` budget does the second pass run, taking the largest safe cut
+ * that leaves at least that many MESSAGES in the tail - flagged `keepRelaxed` so
+ * the host can disclose the trade. A caller that passes nothing sees exactly the
+ * behaviour this function has always had, which is what makes the change
+ * backward-compatible by structure rather than by discipline.
  */
 export declare function planCompaction(messages: readonly Message[], opts: PlanCompactionOptions): CompactionPlan | null;
 export interface ValidateHistoryOptions {

package/dist/engine/compaction.js

@@ -66,6 +66,15 @@ function countTurns(messages, from) {
  * `null` — rather than a zero-length head — is what lets §3.8 turn "the recent
  * turns alone exceed the threshold" into a bounded, loud outcome instead of a
  * retry loop against a paid API.
+ *
+ * TWO PASSES, AND THE SECOND ONE IS OPT-IN (`opts.retainMessages`). The first pass
+ * is unchanged: the largest safe cut that leaves `keepRecentTurns` user turns
+ * behind it. Only when that pass finds nothing AND the caller supplied a
+ * `retainMessages` budget does the second pass run, taking the largest safe cut
+ * that leaves at least that many MESSAGES in the tail - flagged `keepRelaxed` so
+ * the host can disclose the trade. A caller that passes nothing sees exactly the
+ * behaviour this function has always had, which is what makes the change
+ * backward-compatible by structure rather than by discipline.
  */
 export function planCompaction(messages, opts) {
     const keep = Math.max(1, Math.floor(opts.keepRecentTurns));
@@ -87,6 +96,39 @@ export function planCompaction(messages, opts) {
             retainedTurns,
         };
     }
+    const retainMessages = opts.retainMessages;
+    if (retainMessages === undefined)
+        return null;
+    return planRelaxed(messages, safe, {
+        protectedPrefix,
+        retainMessages: Math.max(1, Math.floor(retainMessages)),
+    });
+}
+/**
+ * The second pass: the largest safe cut whose tail still holds `retainMessages`.
+ *
+ * THE TAIL LENGTH BOUND AND THE PREFIX EXIT ARE THE TWO RULES THAT MATTER. Without
+ * the length bound a relaxed plan could leave two messages behind, which is not a
+ * continuation window but a truncation; without the unchanged prefix exit a
+ * compacted history with nothing new would be re-summarized (the idempotence guard
+ * `compaction.test.ts` pins).
+ */
+function planRelaxed(messages, safe, opts) {
+    for (let i = safe.length - 1; i >= 0; i -= 1) {
+        const cutIndex = safe[i];
+        if (cutIndex >= messages.length)
+            continue;
+        if (messages.length - cutIndex < opts.retainMessages)
+            continue;
+        if (cutIndex <= opts.protectedPrefix)
+            return null;
+        return {
+            cutIndex,
+            droppedMessages: cutIndex - opts.protectedPrefix,
+            retainedTurns: countTurns(messages, cutIndex),
+            keepRelaxed: true,
+        };
+    }
     return null;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/core",
-  "version": "0.2.51",
+  "version": "0.2.52",
   "description": "AragonAgent core engine — LLM provider adapters, streaming, tool registry/execution, steering, idle watchdog, and an optional isolated-vm sandbox.",
   "license": "MIT",
   "author": "AragonAgent contributors",