@fungi.computer/shiitake 0.1.0 → 0.3.0

package/dist/internal/compaction/session-compaction.js

@@ -1,15 +1,20 @@
 import { isContextOverflow, } from "@fungi.computer/mule/effect";
 import { isRecoverableLength } from "@earendil-works/pi-ai/utils/overflow";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Schema from "effect/Schema";
 import { ShiitakeError } from "../../errors.js";
 import { borrowedView, compact, prepareCompaction, } from "./compaction.js";
-import { estimateContextTokens, estimateTokens, shouldCompact, } from "./utils.js";
-import { appendCompactionNotice, appendCompactionTransition, beginCompactionActivity, buildSessionContext, endCompactionActivity, withdrawnWorkIds, contextMessageIds, commandContextMessage, operatorContextMessage, promptCommand, readSessionContextPath, } from "../woodstock/index.js";
+import { claimSlot, releaseSlot, slotTaken, takeSummary, } from "./compaction-slot.js";
+import { estimateContextTokens, estimateMessageTokens, } from "@earendil-works/pi-ai/utils/estimate";
+import { compactionSummaryMessage, shouldCompact, shouldCompactInBackground, } from "./utils.js";
+import { appendCompactionNotice, appendCompactionTransition, beginCompactionActivity, buildSessionContext, CompactionReceiptSchema, compactionHeadState, endCompactionActivity, withdrawnWorkIds, contextMessageIds, commandContextMessage, operatorContextMessage, placeCompactionTransition, promptCommand, readSessionContextPath, } from "../woodstock/index.js";
 function runtimeFailure(message) {
     return new ShiitakeError("runtime", "rejected", message);
 }
 const commitFailures = {
     handoff: "The compaction handoff failed; the conversation context is unchanged",
+    handoffResult: "The compaction handoff failed: it returned an invalid result; the conversation context is unchanged",
     conflict: "The Session changed during compaction; the conversation context is unchanged",
 };
 /**
@@ -18,9 +23,11 @@ const commitFailures = {
  */
 export class CompactionCommitError extends ShiitakeError {
     phase;
-    constructor(phase) {
+    usage;
+    constructor(phase, usage) {
         super(phase === "conflict" ? "store" : "runtime", phase === "conflict" ? "conflict" : "rejected", commitFailures[phase]);
         this.phase = phase;
+        this.usage = usage;
     }
     get diagnostic() {
         return commitFailures[this.phase];
@@ -57,14 +64,13 @@ function sourceEntries(path, activeWorkId) {
             const compaction = {
                 id: row.id,
                 kind: "compaction",
-                timestamp: row.timestamp,
-                firstKeptEntryId: row.entry.firstKeptEntryId,
-                summary: row.entry.summary,
-                usage: row.entry.usage,
+                head: row.entry.head,
+                model: row.entry.model[0],
+                usage: row.entry.data.usage,
             };
-            entries.push(row.entry.details === undefined
+            entries.push(row.entry.data.details === undefined
                 ? compaction
-                : { ...compaction, details: row.entry.details });
+                : { ...compaction, details: row.entry.data.details });
         }
     }
     return entries;
@@ -73,36 +79,9 @@ function sourceEntries(path, activeWorkId) {
 function readPath(store, sessionId, workId) {
     return Effect.try({
         try: () => readSessionContextPath(store, { sessionId, workId }),
-        catch: (error) => error instanceof ShiitakeError && error.cause === "context_too_large"
-            ? error
-            : runtimeFailure("Woodstock selected lineage is unavailable"),
+        catch: () => runtimeFailure("Woodstock selected lineage is unavailable"),
     });
 }
-/**
- * The compaction owner's context estimate: Pi's usage-plus-trailing count,
- * excluding provider usage that belongs before Woodstock's latest boundary.
- *
- * A provider's reported usage measures the context it actually read, so it
- * is authoritative only while nothing has reshaped that context since. Once
- * a compaction lands, every kept message's own usage figure is stale: it
- * priced the pre-compaction history, not the summary that replaced it. The
- * one safe fallback is a fresh chars/4 estimate of every message still in
- * view, the same method `tokensAfterCompaction` uses when it records the
- * marker's own `tokensAfter` at commit time; trailing-after-usage alone
- * would undercount (even to zero, when the kept tail's own reply is the
- * newest message and nothing followed it).
- */
-export function estimateThresholdContextTokens(path, messages) {
-    const boundary = path.reduce((latest, row) => (row.entry.kind === "compaction" ? row.timestamp : latest), undefined);
-    const estimate = estimateContextTokens(messages);
-    const usageIndex = estimate.lastUsageIndex;
-    const usageMessage = usageIndex === null ? undefined : messages[usageIndex];
-    if (boundary === undefined ||
-        usageMessage?.role !== "assistant" ||
-        usageMessage.timestamp > boundary)
-        return estimate.tokens;
-    return messages.reduce((sum, message) => sum + estimateTokens(message), 0);
-}
 /** The context the model reads once a compaction row becomes the boundary. */
 function tokensAfterCompaction(path, expected, entry, workId) {
     const boundary = {
@@ -113,7 +92,7 @@ function tokensAfterCompaction(path, expected, entry, workId) {
         timestamp: Date.now(),
         entry,
     };
-    return buildSessionContext([...path, boundary], workId).reduce((sum, message) => sum + estimateTokens(message), 0);
+    return buildSessionContext([...path, boundary], workId).reduce((sum, message) => sum + estimateMessageTokens(message), 0);
 }
 /** One exact preparation, handoff, CAS append, and authoritative rebuild. */
 function commitCompaction(input, path, request) {
@@ -134,48 +113,104 @@ function commitCompactionEffect(input, path, request) {
         if (expected === undefined)
             return undefined;
         const result = yield* compact(preparation, input.model, input.stream, request.instructions);
-        if (input.handoff !== undefined)
-            yield* input.handoff
-                .consume(borrowedView(preparation, result, expected.id))
-                .pipe(Effect.mapError(() => new CompactionCommitError("handoff")));
-        const tokensAfter = tokensAfterCompaction(path, expected, {
-            kind: "compaction",
+        const receipt = yield* handOff(input, preparation, result, expected.id);
+        return yield* appendSummary(input, path, result, request, expected.id, receipt);
+    });
+}
+/**
+ * What a handoff may answer. A JS extension's result arrives untyped, so it is
+ * decoded here: an `accepted` receipt must satisfy the entry's own receipt
+ * rule, so an invalid one stops the compaction before anything is written.
+ */
+const HandoffResultSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal("accepted"),
+        receipt: CompactionReceiptSchema,
+    }),
+    Schema.Struct({ type: Schema.Literal("discarded_by_policy") }),
+]);
+const decodeHandoffResult = Schema.decodeUnknownResult(HandoffResultSchema);
+/**
+ * Zookeeper's handoff with the exact arrays, before the destructive append.
+ * Returns the archive receipt to store in the entry that commits, or
+ * `undefined` when no handoff is installed or it discarded by policy.
+ */
+function handOff(input, preparation, result, contextRevision) {
+    if (input.handoff === undefined)
+        return Effect.succeed(undefined);
+    return input.handoff
+        .consume(borrowedView(preparation, result, input.sessionId, contextRevision))
+        .pipe(Effect.mapError(() => new CompactionCommitError("handoff", result.usage)), Effect.flatMap((handed) => {
+        const decoded = decodeHandoffResult(handed);
+        if (decoded._tag === "Failure")
+            return Effect.fail(new CompactionCommitError("handoffResult", result.usage));
+        return Effect.succeed(decoded.success.type === "accepted"
+            ? decoded.success.receipt
+            : undefined);
+    }));
+}
+/**
+ * The row a compaction appends on the leaf `path` ends at, with its measured
+ * `tokensAfter`. `contextRevision` names the last row the summary saw: that leaf
+ * for a blocking commit, the selection tail for a background one.
+ */
+function compactionRow(input, path, result, request, contextRevision, receipt) {
+    const expected = path.at(-1);
+    if (expected === undefined)
+        return undefined;
+    const tokensAfter = tokensAfterCompaction(path, expected, {
+        kind: "compaction",
+        workId: input.workId,
+        head: result.firstKeptEntryId,
+        model: [compactionSummaryMessage(result.summary, Date.now())],
+        data: {
+            reason: request.trigger,
             resumesRun: request.resumesRun,
-            trigger: request.trigger,
-            workId: input.workId,
-            firstKeptEntryId: result.firstKeptEntryId,
-            summary: result.summary,
             tokensBefore: result.tokensBefore,
+            // This probe row only measures the context; the figure it computes
+            // is what the appended row records.
+            tokensAfter: 0,
             usage: result.usage,
-            contextRevision: expected.id,
-        }, input.workId);
-        const committed = yield* Effect.try({
-            try: () => appendCompactionTransition(input.store, {
-                sessionId: input.sessionId,
-                resumesRun: request.resumesRun,
-                trigger: request.trigger,
-                tokensAfter,
-                expectedLeafId: expected.id,
-                workId: input.workId,
-                firstKeptEntryId: result.firstKeptEntryId,
-                summary: result.summary,
-                tokensBefore: result.tokensBefore,
-                usage: result.usage,
-                contextRevision: expected.id,
-                details: result.details,
-            }),
-            catch: (error) => error instanceof ShiitakeError
-                ? error.cause === "conflict"
-                    ? new CompactionCommitError("conflict")
-                    : error
-                : runtimeFailure("Woodstock compaction append failed"),
-        });
-        const committedPath = [...path, committed];
-        return {
-            path: committedPath,
-            messages: buildSessionContext(committedPath, input.workId),
-        };
-    });
+            contextRevision,
+        },
+    }, input.workId);
+    const row = {
+        sessionId: input.sessionId,
+        resumesRun: request.resumesRun,
+        trigger: request.trigger,
+        tokensAfter,
+        expectedLeafId: expected.id,
+        workId: input.workId,
+        head: result.firstKeptEntryId,
+        summary: result.summary,
+        tokensBefore: result.tokensBefore,
+        usage: result.usage,
+        contextRevision,
+        details: result.details,
+    };
+    return receipt === undefined ? row : { ...row, receipt };
+}
+/** The context the run continues from once `committed` ends `path`. */
+function rebuilt(input, path, committed) {
+    const committedPath = [...path, committed];
+    return {
+        path: committedPath,
+        messages: buildSessionContext(committedPath, input.workId),
+    };
+}
+/** CAS-append a blocking compaction on the leaf `path` ends at and rebuild. */
+function appendSummary(input, path, result, request, contextRevision, receipt) {
+    const row = compactionRow(input, path, result, request, contextRevision, receipt);
+    if (row === undefined)
+        return Effect.succeed(undefined);
+    return Effect.try({
+        try: () => appendCompactionTransition(input.store, row),
+        catch: (error) => error instanceof ShiitakeError
+            ? error.cause === "conflict"
+                ? new CompactionCommitError("conflict")
+                : error
+            : runtimeFailure("Woodstock compaction append failed"),
+    }).pipe(Effect.map((committed) => rebuilt(input, path, committed)));
 }
 /** A failure's display-safe reason: owner-closed text or the model's message. */
 function failureDiagnostic(error) {
@@ -185,23 +220,31 @@ function failureDiagnostic(error) {
         return error.message;
     return `Compaction failed (${error.boundary}: ${error.cause})`;
 }
-/** Record a compaction that committed nothing, so clients can show it. */
-function recordNotice(input, trigger, failure) {
+/** Append one compaction notice, so clients can show what committed nothing. */
+function writeNotice(input, notice) {
     return Effect.try({
         try: () => {
-            appendCompactionNotice(input.store, {
-                sessionId: input.sessionId,
-                workId: input.workId,
-                trigger,
-                result: failure === undefined ? "nothing_to_compact" : "failed",
-                diagnostic: failure === undefined ? undefined : failureDiagnostic(failure),
-            });
+            appendCompactionNotice(input.store, notice);
         },
         catch: (error) => error instanceof ShiitakeError
             ? error
             : runtimeFailure("Compaction notice could not be recorded"),
     });
 }
+/** Record a compaction that found nothing to compact, or failed. */
+function recordNotice(input, trigger, failure) {
+    const common = { sessionId: input.sessionId, workId: input.workId, trigger };
+    return writeNotice(input, failure === undefined
+        ? { ...common, result: "nothing_to_compact" }
+        : {
+            ...common,
+            result: "failed",
+            diagnostic: failureDiagnostic(failure),
+            usage: failure instanceof CompactionCommitError
+                ? failure.usage
+                : undefined,
+        });
+}
 /**
  * Run one automatic compaction. A failure is recorded as a notice and the
  * caller keeps its current context; automatic compaction never fails a run.
@@ -211,15 +254,177 @@ function autoCompaction(input, path, request) {
         ? Effect.succeed(result.success)
         : recordNotice(input, request.trigger, result.failure).pipe(Effect.as(undefined))));
 }
-/** Apply the pre-run threshold check, preserving unchanged input on failure. */
-function preRunMessages(input) {
-    if (input.resuming === true ||
-        !shouldCompact(estimateThresholdContextTokens(input.path, input.messages), input.model.contextWindow, input.settings))
-        return Effect.succeed({ path: input.path, messages: input.messages });
-    return autoCompaction(input, input.path, {
+const thresholdRequest = {
+    trigger: "threshold",
+    resumesRun: false,
+};
+/**
+ * Start a background compaction when the context crossed the background
+ * threshold (tokens only), the owner's slot is free and this run has not
+ * stopped trying. `readContext` is the one context read, taken at fork time;
+ * the fiber keeps only the preparation and hands it back with its summary.
+ */
+function startBackground(input, background, contextTokens, readContext) {
+    if (background.stopped ||
+        slotTaken(input.store) ||
+        !shouldCompactInBackground(contextTokens, input.model.contextWindow, input.settings))
+        return Effect.void;
+    return readContext.pipe(Effect.flatMap((path) => forkBackground(input, background.scope, path)), Effect.map((slot) => {
+        if (slot === undefined)
+            background.stopped = true;
+        else
+            background.slot = slot;
+    }));
+}
+/**
+ * Claim the owner's slot and fork the summary into the run's scope:
+ * interrupting the run interrupts it, aborts the provider call and frees the
+ * slot (a deliberate Shiitake difference: Pi's background compaction
+ * outlives an abort). Nothing to compact forks nothing and stays silent, as
+ * automatic compaction does.
+ */
+function forkBackground(input, scope, path) {
+    const tail = path.at(-1);
+    const preparation = prepareCompaction(sourceEntries(path, input.workId), input.settings);
+    if (tail === undefined || preparation === undefined)
+        return Effect.succeed(undefined);
+    return claimSlot(input.store, scope, (handBack) => summarize(input, preparation, tail.id, handBack));
+}
+/** The fiber's work: the summary call, handed back through the slot. */
+function summarize(input, preparation, selectionTail, handBack) {
+    return Effect.suspend(() => {
+        beginCompactionActivity(input.store, input.sessionId, "threshold");
+        return compact(preparation, input.model, input.stream).pipe(Effect.map((result) => {
+            handBack({ preparation, result, selectionTail });
+        }), Effect.ensuring(Effect.sync(() => {
+            endCompactionActivity(input.store, input.sessionId);
+        })));
+    });
+}
+/**
+ * Settle this run's background compaction and place it: at a between-turn
+ * point only once it has finished (`join: false`), or by waiting for it
+ * when the blocking threshold, an overflow or the end of the run arrives.
+ * Joining instead of starting a second compaction is Shiitake's
+ * single-flight policy; Pi does not join.
+ * Undefined while it still runs, or when it settled failed or stale; a
+ * summary or handoff failure becomes the ordinary `failed` notice. Background
+ * notices (`failed`, `stale`) always record trigger `threshold`, the start that
+ * made them; a placed entry takes `request`, standing in for the compaction
+ * the run would have made at that point.
+ */
+function settleBackground(input, background, request, join) {
+    return Effect.suspend(() => {
+        const slot = background.slot;
+        const fiber = slot?.fiber;
+        if (slot === undefined ||
+            fiber === undefined ||
+            (!join && fiber.pollUnsafe() === undefined))
+            return Effect.succeed(undefined);
+        background.slot = undefined;
+        return Effect.result(Fiber.join(fiber).pipe(Effect.flatMap(() => handOffSummary(input, slot)), Effect.flatMap((handedOff) => handedOff === undefined
+            ? Effect.succeed(undefined)
+            : appendPlaced(input, handedOff, request)))).pipe(Effect.flatMap((placed) => {
+            if (placed._tag === "Success" && placed.success !== undefined)
+                return Effect.succeed(placed.success);
+            background.stopped = true;
+            return placed._tag === "Success"
+                ? Effect.succeed(undefined)
+                : recordNotice(input, "threshold", placed.failure).pipe(Effect.as(undefined));
+        }), Effect.ensuring(Effect.sync(() => {
+            releaseSlot(input.store, slot);
+        })));
+    });
+}
+/**
+ * Record a finished summary dropped unplaced: no entry, only its spend.
+ * `stale`: its head moved. `insufficient`: placed, the context would still be
+ * over the limit.
+ */
+function recordDropped(input, result, reason) {
+    return writeNotice(input, {
+        sessionId: input.sessionId,
+        workId: input.workId,
         trigger: "threshold",
-        resumesRun: false,
-    }).pipe(Effect.map((compacted) => compacted ?? { path: input.path, messages: input.messages }));
+        result: reason,
+        usage: result.usage,
+    }).pipe(Effect.as(undefined));
+}
+/**
+ * Placement steps 1-3 (design §3): take the summary out of the slot, check
+ * its head, hand the fork-time arrays to Zookeeper, then release the slot.
+ * Only the result and the selection tail come back, so the summarized prefix
+ * is unreachable before placement reads the context again. A stale summary
+ * never reaches the handoff.
+ *
+ * A summary handed off here can still fail to commit (stale inside the
+ * append, insufficient, or a CAS conflict). Its accepted archive is then
+ * unreferenced and Z5 sweeps it, at most one per run: see the "view" steps
+ * of wiki/3-resources/shiitake-v0.0.1/zookeeper-compaction-handoff.md.
+ */
+function handOffSummary(input, slot) {
+    const summary = takeSummary(slot);
+    if (summary === undefined)
+        return Effect.succeed(undefined);
+    const { result, selectionTail } = summary;
+    return Effect.try({
+        try: () => compactionHeadState(input.store, {
+            sessionId: input.sessionId,
+            head: result.firstKeptEntryId,
+        }),
+        catch: (error) => error instanceof ShiitakeError
+            ? error
+            : runtimeFailure("Woodstock compaction head is unavailable"),
+    }).pipe(Effect.flatMap((head) => head === "stale"
+        ? recordDropped(input, result, "stale")
+        : handOff(input, summary.preparation, result, selectionTail).pipe(Effect.map((receipt) => ({ result, selectionTail, receipt })))), Effect.ensuring(Effect.sync(() => {
+        releaseSlot(input.store, slot);
+    })));
+}
+/**
+ * Placement steps 4-5: one fresh read, then the append on the leaf as it is
+ * now, head-checked again inside the append transaction because the handoff
+ * ran in between. Rows added after the selection tail stay verbatim after
+ * the head; a head that moved meanwhile drops the summary as stale.
+ *
+ * Decided before appending (fix 3, option A): when the placed context would
+ * still be over the limit, the summary is not placed. It is recorded as
+ * `insufficient` and the caller's ordinary path (the blocking compaction, or the
+ * overflow recovery) runs on a fresh read. Placing it would leave a
+ * compaction at the tip, where Pi's preparation finds nothing to compact
+ * (compaction.ts:282), so that ordinary path could never help.
+ */
+function appendPlaced(input, handedOff, request) {
+    return readPath(input.store, input.sessionId, input.workId).pipe(Effect.flatMap((path) => {
+        const row = compactionRow(input, path, handedOff.result, request, handedOff.selectionTail, handedOff.receipt);
+        if (row === undefined)
+            return Effect.succeed(undefined);
+        if (shouldCompact(row.tokensAfter, input.model.contextWindow, input.settings))
+            return recordDropped(input, handedOff.result, "insufficient");
+        return Effect.try({
+            try: () => placeCompactionTransition(input.store, row),
+            catch: (error) => error instanceof ShiitakeError
+                ? error.cause === "conflict"
+                    ? new CompactionCommitError("conflict")
+                    : error
+                : runtimeFailure("Woodstock compaction append failed"),
+        }).pipe(Effect.flatMap((placed) => placed === "stale"
+            ? recordDropped(input, handedOff.result, "stale")
+            : Effect.succeed(rebuilt(input, path, placed))));
+    }));
+}
+/**
+ * Apply the pre-run threshold check, preserving unchanged input on failure.
+ * Below it, the claimed context path may start a background compaction.
+ */
+function preRunMessages(input, background) {
+    const unchanged = { path: input.path, messages: input.messages };
+    if (input.resuming === true)
+        return Effect.succeed(unchanged);
+    const tokens = estimateContextTokens(input.messages).tokens;
+    if (!shouldCompact(tokens, input.model.contextWindow, input.settings))
+        return startBackground(input, background, tokens, Effect.succeed(input.path)).pipe(Effect.as(unchanged));
+    return autoCompaction(input, input.path, thresholdRequest).pipe(Effect.map((compacted) => compacted ?? unchanged));
 }
 function classifyRecovery(outcome, model) {
     const overflow = isContextOverflow(outcome.message, model.contextWindow);
@@ -240,51 +445,74 @@ function removeFailedAssistant(messages) {
 function postRunPath(input, working, outcome, recovery) {
     if (!input.settings.enabled)
         return Effect.succeed(undefined);
-    const threshold = shouldCompact(estimateThresholdContextTokens(working.path, [
+    const threshold = shouldCompact(estimateContextTokens([
         ...working.messages,
         ...outcome.messages.slice(working.newMessageCount),
-    ]), input.model.contextWindow, input.settings);
+    ]).tokens, input.model.contextWindow, input.settings);
     return recovery.triggered || threshold
         ? readPath(input.store, input.sessionId, input.workId)
         : Effect.succeed(undefined);
 }
 /**
- * Pi's between-turn threshold check: when a running work's context has grown
- * past the threshold, compact the durable lineage (which already holds this
- * turn's tool results) and continue from the rebuilt context.
+ * Pi's between-turn point, where Mule is paused and the run is the only
+ * writer. A finished background summary is placed here; past the blocking
+ * threshold a running one is joined, and only if that placed nothing does
+ * the blocking compaction run. Below it, a background compaction may start.
  */
-function betweenTurns(input, working) {
+function betweenTurns(input, working, background) {
     return (context, newMessageCount) => Effect.gen(function* () {
-        if (!shouldCompact(estimateThresholdContextTokens(working.path, context), input.model.contextWindow, input.settings))
-            return undefined;
-        const path = yield* readPath(input.store, input.sessionId, input.workId);
-        const compacted = yield* autoCompaction(input, path, {
-            trigger: "threshold",
-            resumesRun: false,
-        });
-        if (compacted === undefined)
+        const replace = (compacted) => {
+            working.path = compacted.path;
+            working.messages = compacted.messages;
+            working.newMessageCount = newMessageCount;
+            return compacted.messages;
+        };
+        const tokens = estimateContextTokens(context).tokens;
+        const blocking = shouldCompact(tokens, input.model.contextWindow, input.settings);
+        const placed = yield* settleBackground(input, background, thresholdRequest, blocking);
+        if (placed !== undefined)
+            return replace(placed);
+        const readContext = readPath(input.store, input.sessionId, input.workId);
+        if (!blocking) {
+            yield* startBackground(input, background, tokens, readContext);
             return undefined;
-        working.path = compacted.path;
-        working.messages = compacted.messages;
-        working.newMessageCount = newMessageCount;
-        return compacted.messages;
+        }
+        const compacted = yield* autoCompaction(input, yield* readContext, thresholdRequest);
+        return compacted === undefined ? undefined : replace(compacted);
     });
 }
 /** Run terminal outcomes through post-threshold and one-time recovery policy. */
-function postRunOutcome(input, initial) {
+function postRunOutcome(input, initial, background) {
     return Effect.gen(function* () {
         let current = initial;
         let recoveryAttempted = initial.path.some(({ entry }) => entry.kind === "compaction" &&
             entry.workId === input.workId &&
-            entry.resumesRun === true);
+            entry.data.resumesRun);
         for (;;) {
             const working = {
                 path: current.path,
                 messages: current.messages,
                 newMessageCount: 0,
             };
-            const outcome = yield* input.run(working.messages, betweenTurns(input, working));
+            const outcome = yield* input.run(working.messages, betweenTurns(input, working, background));
             const recovery = classifyRecovery(outcome, input.model);
+            const retry = recovery.retry && !recoveryAttempted;
+            // A summary still running when the run ends is waited for and placed
+            // first; it then stands in for the post-run compaction.
+            const placed = yield* settleBackground(input, background, {
+                trigger: recovery.overflow ? "overflow" : "threshold",
+                resumesRun: retry,
+            }, true);
+            if (placed !== undefined) {
+                if (!retry)
+                    return outcome;
+                current = {
+                    path: placed.path,
+                    messages: removeFailedAssistant(placed.messages),
+                };
+                recoveryAttempted = true;
+                continue;
+            }
             const path = yield* postRunPath(input, working, outcome, recovery);
             if (path === undefined)
                 return outcome;
@@ -304,11 +532,22 @@ function postRunOutcome(input, initial) {
         }
     });
 }
-/** Compose the retained pre-run, between-turn and post-run compaction phases. */
+/**
+ * Compose the retained pre-run, between-turn and post-run compaction phases.
+ * A background compaction is a child fiber in the run's own scope.
+ */
 export function runWithCompaction(input) {
-    if (!input.settings.enabled)
-        return postRunOutcome(input, input);
-    return preRunMessages(input).pipe(Effect.flatMap((initial) => postRunOutcome(input, initial)));
+    return Effect.gen(function* () {
+        const background = {
+            scope: yield* Effect.scope,
+            slot: undefined,
+            stopped: false,
+        };
+        const initial = input.settings.enabled
+            ? yield* preRunMessages(input, background)
+            : input;
+        return yield* postRunOutcome(input, initial, background);
+    });
 }
 /**
  * Compact one Session now, as accepted work: the same commit the automatic

package/dist/internal/compaction/settings.js

@@ -5,11 +5,13 @@ const tokens = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)), S
 const BudgetSchema = Schema.Struct({
     reserveTokens: Schema.optionalKey(tokens),
     keepRecentTokens: Schema.optionalKey(tokens),
+    backgroundTokens: Schema.optionalKey(tokens),
 });
 const CompactionOptionsSchema = Schema.Struct({
     enabled: Schema.optionalKey(Schema.Boolean),
     reserveTokens: Schema.optionalKey(tokens),
     keepRecentTokens: Schema.optionalKey(tokens),
+    backgroundTokens: Schema.optionalKey(tokens),
     modelOverrides: Schema.optionalKey(Schema.Record(Schema.String, BudgetSchema)),
 });
 const decodeOptions = Schema.decodeUnknownResult(CompactionOptionsSchema, {
@@ -35,6 +37,9 @@ export function openCompactionSettings(options) {
             keepRecentTokens: override?.keepRecentTokens ??
                 settings.keepRecentTokens ??
                 DEFAULT_COMPACTION_SETTINGS.keepRecentTokens,
+            backgroundTokens: override?.backgroundTokens ??
+                settings.backgroundTokens ??
+                DEFAULT_COMPACTION_SETTINGS.backgroundTokens,
         };
     };
 }