@bastani/atomic 0.9.12 → 0.9.13-alpha.2

package/dist/core/agent-session-auto-compaction.d.ts

@@ -1,18 +1,23 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai/compat";
-import type { AgentSessionInternalSurface as AgentSession } from "./agent-session-methods.ts";
+import type { AgentSessionInternalSurface as AgentSession, AutoCompactionRunOutcome } from "./agent-session-methods.ts";
+import { type CompactionUrgency } from "./compaction/index.ts";
 /**
- * Upper bound on consecutive automatic continuations of a response that was
- * truncated at the output-token cap ("length") while the context is still
- * below the compaction budget. Each continuation regenerates the cut-off turn,
- * so a model that insists on emitting more than its per-turn output cap can
- * still terminate instead of looping forever.
+ * Upper bound on direct continuations after a response reaches its requested
+ * output cap. Context-limited truncations use one compact-and-retry attempt
+ * instead; this bound preserves Atomic's separate output-cap continuation.
  */
 export declare const MAX_LENGTH_CONTINUATION_ATTEMPTS = 3;
 export declare const MAX_OUTPUT_BUDGET_ERROR_CONTINUATION_ATTEMPTS = 1;
+/** Create the settlement boundary for a regular automatic compaction run. */
+export declare function createAutoCompactionCompletion(): {
+    promise: Promise<void>;
+    resolve: () => void;
+};
 export declare function _checkCompaction(this: AgentSession, assistantMessage: AssistantMessage, skipAbortedCheck?: boolean): Promise<void>;
 export declare function isRetryWorthyLengthStop(assistantMessage: AssistantMessage): boolean;
+export declare function isOutputCappedLengthStop(assistantMessage: AssistantMessage, desiredMaxOutput: number): boolean;
 export declare function isRetryWorthyOutputBudgetError(assistantMessage: AssistantMessage): boolean;
-export declare function shouldRetryAfterThresholdCompaction(assistantMessage: AssistantMessage): boolean;
+export declare function shouldRetryAfterThresholdCompaction(assistantMessage: AssistantMessage, desiredMaxOutput: number, isLiveTurnCompletion: boolean): boolean;
 /**
  * Internal: remove an incomplete assistant from retry context before auto-continuing after compaction.
  */
@@ -30,14 +35,13 @@ export declare function _awaitPendingPostCompactionContinuation(this: AgentSessi
  */
 export declare function _resumeAfterAutoCompaction(this: AgentSession): Promise<void>;
 /**
- * Internal: resume a response that was truncated at the output-token cap
- * ("length") when the context does not warrant compaction. The generation is
- * continued directly so the model finishes the work it was cut off from, rather
- * than dead-ending on the truncation. Bounded by MAX_LENGTH_CONTINUATION_ATTEMPTS
- * so a turn that keeps exceeding the per-turn output cap can still terminate.
+ * Internal: resume a response that reached its requested output cap when the
+ * context does not warrant compaction. Bounded so a model that repeatedly
+ * stops at that cap can still terminate.
  */
 export declare function _resumeAfterLengthTruncation(this: AgentSession): void;
-export declare function _runAutoCompaction(this: AgentSession, reason: "overflow" | "threshold", willRetry: boolean): Promise<void>;
+export declare function hasPendingManualCompactionTakeover(this: AgentSession): boolean;
+export declare function _runAutoCompaction(this: AgentSession, reason: "overflow" | "threshold", willRetry: boolean, urgency?: CompactionUrgency): Promise<AutoCompactionRunOutcome>;
 /**
  * Toggle auto-compaction setting.
  */

package/dist/core/agent-session-auto-compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-session-auto-compaction.d.ts","sourceRoot":"","sources":["../../src/core/agent-session-auto-compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,KAAK,EAAE,2BAA2B,IAAI,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAK9F;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,eAAO,MAAM,6CAA6C,IAAI,CAAC;AAc/D,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,YAAY,EAClB,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,UAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAuIf;AAED,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAEnF;AAqDD,wBAAgB,8BAA8B,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAQ1F;AAED,wBAAgB,mCAAmC,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAE/F;AAED;;GAEG;AAEH,wBAAgB,kDAAkD,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAQ3F;AAED;;;;;GAKG;AAEH,wBAAgB,4CAA4C,CAC3D,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,UAAU,GAAG,WAAW,EACjC,SAAS,EAAE,OAAO,GAChB,IAAI,CA4BN;AAED,wBAAsB,uCAAuC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/F;AAED;;GAEG;AAEH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAWlF;AAED;;;;;;GAMG;AAEH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAQrE;AAMD,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,UAAU,GAAG,WAAW,EAChC,SAAS,EAAE,OAAO,GAChB,OAAO,CAAC,IAAI,CAAC,CAwFf;AAED;;GAEG;AAEH,eAAO,MAAM,iCAAiC;;;;;;;;CAQ7C,CAAC"}
+{"version":3,"file":"agent-session-auto-compaction.d.ts","sourceRoot":"","sources":["../../src/core/agent-session-auto-compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,KAAK,EAAE,2BAA2B,IAAI,YAAY,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACxH,OAAO,EACN,KAAK,iBAAiB,EAItB,MAAM,uBAAuB,CAAC;AAI/B;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,eAAO,MAAM,6CAA6C,IAAI,CAAC;AAS/D,6EAA6E;AAC7E,wBAAgB,8BAA8B,IAAI;IACjD,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB,CAMA;AAOD,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,YAAY,EAClB,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,UAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAmLf;AAED,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAEnF;AAED,wBAAgB,wBAAwB,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAE9G;AAqDD,wBAAgB,8BAA8B,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAQ1F;AAED,wBAAgB,mCAAmC,CAClD,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,EAAE,MAAM,EACxB,oBAAoB,EAAE,OAAO,GAC3B,OAAO,CAKT;AAED;;GAEG;AAEH,wBAAgB,kDAAkD,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAQ3F;AAED;;;;;GAKG;AAEH,wBAAgB,4CAA4C,CAC3D,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,UAAU,GAAG,WAAW,EACjC,SAAS,EAAE,OAAO,GAChB,IAAI,CA0DN;AAED,wBAAsB,uCAAuC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/F;AAED;;GAEG;AAEH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAWlF;AAED;;;;GAIG;AAEH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAQrE;AAYD,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAE9E;AAED,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,UAAU,GAAG,WAAW,EAChC,SAAS,EAAE,OAAO,EAClB,OAAO,GAAE,iBAA0E,GACjF,OAAO,CAAC,wBAAwB,CAAC,CAmHnC;AAED;;GAEG;AAEH,eAAO,MAAM,iCAAiC;;;;;;;;CAQ7C,CAAC"}

package/dist/core/agent-session-auto-compaction.js

@@ -1,16 +1,22 @@
-import { isContextOverflow } from "@earendil-works/pi-ai/compat";
-import { calculateContextTokens, estimateContextTokens, shouldCompact } from "./compaction/index.js";
+import { isContextOverflow, isRecoverableLength } from "@earendil-works/pi-ai/compat";
+import { calculateContextTokens, estimateContextTokens, shouldCompact, } from "./compaction/index.js";
 import { MIN_RESPONSES_MAX_OUTPUT_TOKENS } from "./openai-responses-payload-sanitizer.js";
 import { getLatestCompactionBoundaryEntry } from "./session-manager.js";
 /**
- * Upper bound on consecutive automatic continuations of a response that was
- * truncated at the output-token cap ("length") while the context is still
- * below the compaction budget. Each continuation regenerates the cut-off turn,
- * so a model that insists on emitting more than its per-turn output cap can
- * still terminate instead of looping forever.
+ * Upper bound on direct continuations after a response reaches its requested
+ * output cap. Context-limited truncations use one compact-and-retry attempt
+ * instead; this bound preserves Atomic's separate output-cap continuation.
  */
 export const MAX_LENGTH_CONTINUATION_ATTEMPTS = 3;
 export const MAX_OUTPUT_BUDGET_ERROR_CONTINUATION_ATTEMPTS = 1;
+/** Create the settlement boundary for a regular automatic compaction run. */
+export function createAutoCompactionCompletion() {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
 const OUTPUT_BUDGET_PARAMETER_PATTERN = /\bmax_output_tokens\b/;
 const OUTPUT_BUDGET_UNDERFLOW_PATTERN = new RegExp(`(?:integer\\s+below\\s+minimum\\s+value|expected\\s+(?:a\\s+)?value\\s*>=\\s*${MIN_RESPONSES_MAX_OUTPUT_TOKENS}|got\\s+1\\s+instead)`);
 export async function _checkCompaction(assistantMessage, skipAbortedCheck = true) {
@@ -24,6 +30,7 @@ export async function _checkCompaction(assistantMessage, skipAbortedCheck = true
             aborted: true,
             willRetry: false,
             midTurn: true,
+            ...(hasPendingManualCompactionTakeover.call(this) ? { manualTakeoverPending: true } : {}),
         });
     }
     if (this._postToolCompactionPreflightError !== undefined &&
@@ -36,17 +43,25 @@ export async function _checkCompaction(assistantMessage, skipAbortedCheck = true
     // response — before a fresh user prompt we must not resume the old turn.
     const isLiveTurnCompletion = skipAbortedCheck;
     const settings = this.settingsManager.getCompactionSettings();
-    if (!settings.enabled)
-        return;
-    // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
-    if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
-        return;
     const contextWindow = this.model?.contextWindow ?? 0;
-    // Skip overflow check if the message came from a different model.
+    // Skip overflow handling if the message came from a different model.
     // This handles the case where user switched from a smaller-context model (e.g. opus)
     // to a larger-context model (e.g. codex) - the overflow error from the old model
     // shouldn't trigger compaction for the new model.
-    const sameModel = this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;
+    const sameModel = this.model !== undefined &&
+        assistantMessage.provider === this.model.provider &&
+        assistantMessage.model === this.model.id;
+    const contextOverflow = sameModel && isContextOverflow(assistantMessage, contextWindow);
+    if (!settings.enabled) {
+        // Compaction cannot recover this turn, so a configured fallback chain may
+        // advance to a larger-context candidate instead of dead-ending.
+        if (contextOverflow)
+            this._contextOverflowUnresolved = true;
+        return;
+    }
+    // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
+    if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
+        return;
     // Skip compaction checks if this assistant message is older than the latest
     // compaction boundary. This prevents a stale pre-compaction usage/error
     // from retriggering compaction on the first prompt after compaction.
@@ -56,33 +71,74 @@ export async function _checkCompaction(assistantMessage, skipAbortedCheck = true
     if (assistantIsFromBeforeCompactionBoundary) {
         return;
     }
-    // Case 1: Overflow - LLM returned context overflow error
-    if (sameModel && isContextOverflow(assistantMessage, contextWindow)) {
+    // Case 1: Recoverable failure. Explicit/silent context overflow still uses
+    // context metadata. A length stop below the model's original requested output
+    // cap instead receives one compact-and-retry independent of context metadata.
+    // This recovers a chat response; `truncated-range-recovery` separately parses
+    // deletion records from a compaction planner response and is not involved here.
+    const desiredMaxOutput = this.model?.maxTokens ?? 0;
+    const recoverableLength = isLiveTurnCompletion && sameModel && isRecoverableLength(assistantMessage, desiredMaxOutput);
+    if (contextOverflow || recoverableLength) {
         const willRetry = assistantMessage.stopReason !== "stop";
         if (!willRetry) {
             await this._runAutoCompaction("overflow", false);
             return;
         }
-        if (this._overflowRecoveryAttempted) {
+        const recoveryAttempted = contextOverflow
+            ? this._overflowRecoveryAttempted
+            : this._recoverableLengthRecoveryAttempted;
+        if (recoveryAttempted) {
+            // One recovery of this kind has already been spent on this turn. A real
+            // context overflow may now advance to a larger-context fallback; a
+            // recoverable output truncation stops without claiming overflow.
+            if (contextOverflow)
+                this._contextOverflowUnresolved = true;
             this._emit({
                 type: "compaction_end",
                 reason: "overflow",
                 result: undefined,
                 aborted: false,
                 willRetry: false,
-                unresolvedOverflow: true,
-                errorMessage: "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.",
+                ...(contextOverflow ? { unresolvedOverflow: true } : {}),
+                errorMessage: contextOverflow
+                    ? "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model."
+                    : "Response truncation recovery stopped after one retry.",
             });
             return;
         }
-        this._overflowRecoveryAttempted = true;
-        // Remove the error message from agent state (it IS saved to session for history,
-        // but we don't want it in context for the retry)
-        const messages = this.agent.state.messages;
-        if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-            this.agent.state.messages = messages.slice(0, -1);
+        if (contextOverflow)
+            this._overflowRecoveryAttempted = true;
+        else
+            this._recoverableLengthRecoveryAttempted = true;
+        let outcome;
+        try {
+            outcome = contextOverflow
+                ? await this._runAutoCompaction("overflow", willRetry)
+                : await this._runAutoCompaction("overflow", willRetry, "recoverable");
+        }
+        catch (error) {
+            if (contextOverflow)
+                this._overflowRecoveryAttempted = false;
+            else
+                this._recoverableLengthRecoveryAttempted = false;
+            throw error;
+        }
+        if (outcome === "compacted" || outcome === "failed")
+            return;
+        // No boundary means there is no context to free. Keep this recovery
+        // attempt spent while its one direct continuation is pending, so another
+        // below-cap stop cannot start a new compaction cycle.
+        if (recoverableLength &&
+            outcome === "not_compactable" &&
+            this._compactionAbortController === undefined &&
+            this._manualCompactionPromise === undefined) {
+            this._resumeAfterLengthTruncation();
+            return;
         }
-        await this._runAutoCompaction("overflow", willRetry);
+        if (contextOverflow)
+            this._overflowRecoveryAttempted = false;
+        else
+            this._recoverableLengthRecoveryAttempted = false;
         return;
     }
     // Case 2: Threshold - context is getting large
@@ -109,7 +165,7 @@ export async function _checkCompaction(assistantMessage, skipAbortedCheck = true
         contextTokens = calculateContextTokens(assistantMessage.usage, assistantMessage.api);
     }
     if (shouldCompact(contextTokens, contextWindow, settings)) {
-        const willRetry = shouldRetryAfterThresholdCompaction(assistantMessage);
+        const willRetry = shouldRetryAfterThresholdCompaction(assistantMessage, desiredMaxOutput, isLiveTurnCompletion);
         if (willRetry && isRetryWorthyOutputBudgetError(assistantMessage)) {
             if (this._outputBudgetErrorContinuationAttempts >= MAX_OUTPUT_BUDGET_ERROR_CONTINUATION_ATTEMPTS) {
                 this._emit({
@@ -127,18 +183,22 @@ export async function _checkCompaction(assistantMessage, skipAbortedCheck = true
         await this._runAutoCompaction("threshold", willRetry);
         return;
     }
-    // A response truncated at the output-token cap ("length") with the context
-    // still below the compaction budget is genuine work cut off mid-flight, not a
-    // context overflow. Compaction would not free any room, so continue the
-    // generation directly instead of dead-ending on the truncation and leaving
-    // the task half-finished.
-    if (isLiveTurnCompletion && isRetryWorthyLengthStop(assistantMessage)) {
+    // A length stop that reached its requested output cap is not the
+    // context-limited truncation recovered above. Preserve Atomic's bounded
+    // direct-continuation policy for that distinct case.
+    if (isLiveTurnCompletion &&
+        isOutputCappedLengthStop(assistantMessage, desiredMaxOutput) &&
+        this._compactionAbortController === undefined &&
+        this._manualCompactionPromise === undefined) {
         this._resumeAfterLengthTruncation();
     }
 }
 export function isRetryWorthyLengthStop(assistantMessage) {
     return assistantMessage.stopReason === "length" && assistantMessage.usage.output > 0;
 }
+export function isOutputCappedLengthStop(assistantMessage, desiredMaxOutput) {
+    return isRetryWorthyLengthStop(assistantMessage) && !isRecoverableLength(assistantMessage, desiredMaxOutput);
+}
 function isJsonRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -196,8 +256,9 @@ export function isRetryWorthyOutputBudgetError(assistantMessage) {
         return true;
     return isOutputBudgetUnderflowText(assistantMessage.errorMessage);
 }
-export function shouldRetryAfterThresholdCompaction(assistantMessage) {
-    return isRetryWorthyLengthStop(assistantMessage) || isRetryWorthyOutputBudgetError(assistantMessage);
+export function shouldRetryAfterThresholdCompaction(assistantMessage, desiredMaxOutput, isLiveTurnCompletion) {
+    return (isRetryWorthyOutputBudgetError(assistantMessage) ||
+        (isLiveTurnCompletion && isOutputCappedLengthStop(assistantMessage, desiredMaxOutput)));
 }
 /**
  * Internal: remove an incomplete assistant from retry context before auto-continuing after compaction.
@@ -221,10 +282,24 @@ export function _dropTrailingAutoCompactionRetryAssistantIfPresent() {
 export function _schedulePostAutoCompactionContinuationProbe(_reason, willRetry) {
     const token = this._postCompactionContinuationToken + 1;
     this._postCompactionContinuationToken = token;
+    const fallbackScopeGeneration = this._fallbackOriginGeneration;
     let pending;
     pending = new Promise((resolve) => {
         setTimeout(() => {
             void (async () => {
+                const restoreIfOwned = async () => {
+                    if (fallbackScopeGeneration === undefined ||
+                        this._fallbackOriginGeneration !== fallbackScopeGeneration ||
+                        typeof this._restoreFallbackModel !== "function")
+                        return;
+                    try {
+                        await this._restoreFallbackModel();
+                    }
+                    catch {
+                        // A listener must not strand the continuation waiter. The model
+                        // state was already restored before lifecycle notifications ran.
+                    }
+                };
                 try {
                     if (willRetry) {
                         if (this._postCompactionContinuationToken !== token)
@@ -238,10 +313,24 @@ export function _schedulePostAutoCompactionContinuationProbe(_reason, willRetry)
                             return;
                         if (this.isCompacting || this.isStreaming)
                             return;
-                        if (!this.agent.hasQueuedMessages())
+                        if (!this.agent.hasQueuedMessages()) {
+                            await restoreIfOwned();
                             return;
+                        }
+                        // A queued message starts the next user turn. Restore before
+                        // Agent snapshots the next request's model.
+                        await restoreIfOwned();
                     }
+                    if (this._pendingPostCompactionContinuation !== pending)
+                        return;
+                    // Clear this probe before entering the next run. Its promise is
+                    // still awaited by _awaitPendingPostCompactionContinuation, but
+                    // the nested agent_end must be free to schedule a new probe.
+                    this._pendingPostCompactionContinuation = undefined;
                     await this._resumeAfterAutoCompaction();
+                    if (willRetry && this._pendingPostCompactionContinuation === undefined) {
+                        await restoreIfOwned();
+                    }
                 }
                 finally {
                     if (this._pendingPostCompactionContinuation === pending) {
@@ -277,11 +366,9 @@ export async function _resumeAfterAutoCompaction() {
     }
 }
 /**
- * Internal: resume a response that was truncated at the output-token cap
- * ("length") when the context does not warrant compaction. The generation is
- * continued directly so the model finishes the work it was cut off from, rather
- * than dead-ending on the truncation. Bounded by MAX_LENGTH_CONTINUATION_ATTEMPTS
- * so a turn that keeps exceeding the per-turn output cap can still terminate.
+ * Internal: resume a response that reached its requested output cap when the
+ * context does not warrant compaction. Bounded so a model that repeatedly
+ * stops at that cap can still terminate.
  */
 export function _resumeAfterLengthTruncation() {
     if (this._lengthContinuationAttempts >= MAX_LENGTH_CONTINUATION_ATTEMPTS)
@@ -293,15 +380,28 @@ export function _resumeAfterLengthTruncation() {
     this._dropTrailingAutoCompactionRetryAssistantIfPresent();
     this._schedulePostAutoCompactionContinuationProbe("threshold", true);
 }
-function overflowUnresolved(reason, aborted = false) {
-    return reason === "overflow" && !aborted ? true : undefined;
+/**
+ * Whether an overflow turn is now unrecoverable by compaction, recording it on
+ * the session so a configured fallback chain may advance to another candidate.
+ */
+function overflowUnresolved(loadBearing, aborted = false) {
+    if (!loadBearing || aborted)
+        return undefined;
+    this._contextOverflowUnresolved = true;
+    return true;
+}
+export function hasPendingManualCompactionTakeover() {
+    return this._compactionReason === "manual" && this._compactionAbortController !== undefined;
 }
-export async function _runAutoCompaction(reason, willRetry) {
-    // Publish automatic ownership before notifying listeners. `_emit()` invokes
-    // public listeners synchronously, so a `compaction_start` listener that calls
-    // `compact()` must already observe this controller and be rejected rather than
-    // racing the run that was just announced.
-    this._autoCompactionAbortController = new AbortController();
+export async function _runAutoCompaction(reason, willRetry, urgency = reason === "overflow" ? "load_bearing" : "recoverable") {
+    if (this._compactionAbortController !== undefined ||
+        this._manualCompactionPromise !== undefined ||
+        this._autoCompactionAbortController !== undefined)
+        return "deferred";
+    const controller = new AbortController();
+    const completion = createAutoCompactionCompletion();
+    this._autoCompactionAbortController = controller;
+    this._autoCompactionCompletion = completion.promise;
     this._compactionReason = reason;
     try {
         this._emit({ type: "compaction_start", reason });
@@ -309,22 +409,28 @@ export async function _runAutoCompaction(reason, willRetry) {
     catch (error) {
         // A throwing start listener still propagates, matching current behavior,
         // but must not leave ownership published with no owner running.
-        this._autoCompactionAbortController = undefined;
+        if (this._autoCompactionAbortController === controller)
+            this._autoCompactionAbortController = undefined;
         if (this._compactionReason === reason)
             this._compactionReason = undefined;
+        completion.resolve();
+        if (this._autoCompactionCompletion === completion.promise)
+            this._autoCompactionCompletion = undefined;
         throw error;
     }
     try {
         if (!this.model) {
+            const manualTakeoverPending = hasPendingManualCompactionTakeover.call(this);
             this._emit({
                 type: "compaction_end",
                 reason,
                 result: undefined,
                 aborted: false,
                 willRetry: false,
-                unresolvedOverflow: overflowUnresolved(reason),
+                unresolvedOverflow: overflowUnresolved.call(this, urgency === "load_bearing"),
+                ...(manualTakeoverPending ? { manualTakeoverPending: true } : {}),
             });
-            return;
+            return manualTakeoverPending ? "deferred" : "failed";
         }
         // Resolve auth only after extension hooks have had an opportunity to cancel
         // compaction or provide compacted text, so local extension compaction does not
@@ -335,54 +441,73 @@ export async function _runAutoCompaction(reason, willRetry) {
                 const authResult = await this._getRequiredRequestAuth(candidate);
                 return authResult.apiKey || authResult.headers ? authResult : undefined;
             },
-            abortController: this._autoCompactionAbortController,
-            backupLabel: reason === "overflow" ? "overflow-auto-compact" : "auto-compact",
+            abortController: controller,
+            backupLabel: urgency === "load_bearing" ? "overflow-auto-compact" : "auto-compact",
             reason,
-            // Overflow recovery is load-bearing: the turn cannot continue without it.
-            // A threshold crossing has already passed its turn boundary, so failing is safe.
-            urgency: reason === "overflow" ? "load_bearing" : "recoverable",
-            // A real provider overflow already proved the context does not fit, so a
-            // sub-minimum region may reach the fresh rung.
-            ...(reason === "overflow" ? { allowSmallRegion: true } : {}),
+            urgency,
+            // Only an actual context overflow proved the context cannot fit. A
+            // recoverable length stop must never reach the fresh-context fallback.
+            ...(urgency === "load_bearing" ? { allowSmallRegion: true } : {}),
         });
         if (!result) {
+            const manualTakeoverPending = hasPendingManualCompactionTakeover.call(this);
             this._emit({
                 type: "compaction_end",
                 reason,
                 result: undefined,
                 aborted: false,
                 willRetry: false,
-                unresolvedOverflow: overflowUnresolved(reason),
+                unresolvedOverflow: overflowUnresolved.call(this, urgency === "load_bearing"),
+                ...(manualTakeoverPending ? { manualTakeoverPending: true } : {}),
             });
-            return;
+            return manualTakeoverPending ? "deferred" : "not_compactable";
         }
         if (willRetry) {
             this._dropTrailingAutoCompactionRetryAssistantIfPresent();
         }
-        this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry });
-        this._schedulePostAutoCompactionContinuationProbe(reason, willRetry);
+        this._emit({
+            type: "compaction_end",
+            reason,
+            result,
+            aborted: false,
+            willRetry,
+            ...(hasPendingManualCompactionTakeover.call(this) ? { manualTakeoverPending: true } : {}),
+        });
+        if (!hasPendingManualCompactionTakeover.call(this)) {
+            this._schedulePostAutoCompactionContinuationProbe(reason, willRetry);
+        }
+        return "compacted";
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "compaction failed";
         const aborted = errorMessage === "Compaction cancelled" || (error instanceof Error && error.name === "AbortError");
+        const manualTakeoverPending = hasPendingManualCompactionTakeover.call(this);
         this._emit({
             type: "compaction_end",
             reason,
             result: undefined,
             aborted,
             willRetry: false,
-            unresolvedOverflow: overflowUnresolved(reason, aborted),
+            unresolvedOverflow: overflowUnresolved.call(this, urgency === "load_bearing", aborted),
+            ...(manualTakeoverPending ? { manualTakeoverPending: true } : {}),
             errorMessage: aborted
                 ? undefined
                 : reason === "overflow"
-                    ? `Context overflow recovery failed: ${errorMessage}`
+                    ? urgency === "recoverable"
+                        ? `Response truncation recovery failed: ${errorMessage}`
+                        : `Context overflow recovery failed: ${errorMessage}`
                     : `Auto-compaction failed: ${errorMessage}`,
         });
+        return manualTakeoverPending ? "deferred" : "failed";
     }
     finally {
-        this._autoCompactionAbortController = undefined;
+        if (this._autoCompactionAbortController === controller)
+            this._autoCompactionAbortController = undefined;
         if (this._compactionReason === reason)
             this._compactionReason = undefined;
+        completion.resolve();
+        if (this._autoCompactionCompletion === completion.promise)
+            this._autoCompactionCompletion = undefined;
     }
 }
 /**