@aexol/spectral 0.9.58 → 0.9.59

package/dist/memory/tools/compact-context.js

@@ -0,0 +1,772 @@
+import { Type } from "../../sdk/ai/index.js";
+import { compactDcpLite, DEFAULT_COMPACTION_POLICY, estimateContextTokens, getManualCompactionSettings, normalizeAgentDrivenOlderHistoryKeepRecentTokens, prepareCompaction, } from "../../sdk/coding-agent/core/compaction/index.js";
+import { defineTool } from "../../sdk/coding-agent/index.js";
+import { buildSessionContext } from "../../sdk/coding-agent/core/session-manager.js";
+import { rawTokensSinceLastCompaction } from "../branch.js";
+import { debugLog, withDebugLogContext } from "../debug-log.js";
+export const COMPACT_CONTEXT_TOOL_NAME = "compact_context";
+const DCP_NUDGE_HEADING = "## DCP-lite context hygiene";
+const MAX_COMPACT_CONTEXT_TEXT_CHARS = 240;
+const MAX_CUSTOM_INSTRUCTIONS_CHARS = 640;
+const DEFAULT_COMPACT_CONTEXT_SCOPE = "closed_phase";
+const DEFAULT_COMPACT_CONTEXT_MODE = "after_turn";
+const REQUEST_TIME_VIRTUAL_COMPACTION_ID = "__spectral_dcp_lite_request_time_compaction__";
+const COMPACT_CONTEXT_TOOL_PARAMS = Type.Object({
+    scope: Type.Optional(Type.Union([
+        Type.Literal("closed_phase"),
+        Type.Literal("older_history"),
+    ], {
+        description: "Compaction scope. closed_phase (default) compacts the completed phase boundary. older_history compacts stale older history while preserving a recent raw suffix.",
+    })),
+    reason: Type.Optional(Type.String({
+        description: "Short reason compaction is safe now, e.g. 'implementation phase complete'.",
+    })),
+    focus: Type.Optional(Type.String({
+        description: "Short topic/focus for the compaction summary, e.g. 'preserve verification status and changed files'.",
+    })),
+    phase: Type.Optional(Type.String({
+        description: "Optional completed phase or topic name, e.g. 'implementation' or 'verification'.",
+    })),
+    customInstructions: Type.Optional(Type.String({
+        description: "Optional concise custom preservation instructions. Overrides generated reason/focus/phase text when provided.",
+    })),
+    phaseComplete: Type.Optional(Type.Boolean({
+        description: "Set false if the current phase is still active/open; false rejects closed_phase activation but can be used with older_history.",
+    })),
+    phaseStatus: Type.Optional(Type.Union([
+        Type.Literal("complete"),
+        Type.Literal("completed"),
+        Type.Literal("done"),
+        Type.Literal("closed"),
+        Type.Literal("active"),
+        Type.Literal("open"),
+        Type.Literal("in_progress"),
+    ], {
+        description: "Optional explicit phase status. active/open/in_progress rejects closed_phase activation but can be used with older_history.",
+    })),
+    keepRecentTokens: Type.Optional(Type.Number({
+        description: "For scope=older_history only: recent raw suffix to preserve. Values are conservatively bounded before activation.",
+    })),
+    mode: Type.Optional(Type.Union([
+        Type.Literal("request_time"),
+        Type.Literal("after_turn"),
+    ], {
+        description: "When to compact. When omitted, the mode is chosen automatically: request_time (virtual pruning of the next provider request, no session mutation) while the agent is mid-run with an active phase; after_turn (persisted post-run compaction) when idle or the phase is closed. Pass explicitly to override.",
+    })),
+});
+const stateByRuntime = new WeakMap();
+function getState(runtime) {
+    let state = stateByRuntime.get(runtime);
+    if (!state) {
+        state = {
+            request: null,
+            nudgeTurnCount: 0,
+            lastNudgeTurn: 0,
+            lastAgentDrivenRequestTurn: null,
+            providerRequestCount: 0,
+            lastInRunNudgeRequest: 0,
+        };
+        stateByRuntime.set(runtime, state);
+    }
+    return state;
+}
+function normalizeText(value, maxChars) {
+    const normalized = value?.replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return undefined;
+    return normalized.length <= maxChars
+        ? normalized
+        : `${normalized.slice(0, maxChars - 1).trimEnd()}…`;
+}
+function buildCustomInstructions(params) {
+    const customInstructions = normalizeText(params.customInstructions, MAX_CUSTOM_INSTRUCTIONS_CHARS);
+    if (customInstructions)
+        return customInstructions;
+    const focus = normalizeText(params.focus, MAX_COMPACT_CONTEXT_TEXT_CHARS);
+    const reason = normalizeText(params.reason, MAX_COMPACT_CONTEXT_TEXT_CHARS);
+    const phase = normalizeText(params.phase, MAX_COMPACT_CONTEXT_TEXT_CHARS);
+    if (focus && !reason && !phase)
+        return focus;
+    const parts = [];
+    if (phase)
+        parts.push(`Phase: ${phase}`);
+    if (focus)
+        parts.push(`Focus: ${focus}`);
+    if (reason)
+        parts.push(`Reason: ${reason}`);
+    return normalizeText(parts.join(". "), MAX_CUSTOM_INSTRUCTIONS_CHARS);
+}
+function formatTokenCount(tokens) {
+    return Math.round(tokens).toLocaleString();
+}
+function formatSignals(rawTokens, contextTokens, percent, providerRequests) {
+    const parts = [`~${rawTokens.toLocaleString()} raw tokens since last compaction`];
+    if (typeof contextTokens === "number" && Number.isFinite(contextTokens)) {
+        parts.push(`~${formatTokenCount(contextTokens)} context tokens in the next request`);
+    }
+    if (typeof percent === "number" && Number.isFinite(percent)) {
+        parts.push(`${Math.round(percent)}% context window used`);
+    }
+    if (providerRequests !== undefined) {
+        parts.push(`${formatTokenCount(providerRequests)} provider requests since the last user prompt`);
+    }
+    return parts.join(", ");
+}
+function buildDcpNudge(rawTokens, contextTokens, percent, policy, providerRequests) {
+    return [
+        "",
+        DCP_NUDGE_HEADING,
+        `Context is accumulating (${formatSignals(rawTokens, contextTokens, percent, providerRequests)}).`,
+        "Use `compact_context` once when a safe compaction scope is available. When the agent is still working mid-run, the default is virtual `request_time` pruning that shrinks the next provider request without mutating session history; when the phase is closed or the agent is idle, persisted `after_turn` compaction runs after this run for cache-friendly future requests.",
+        "If the user explicitly asks to run/trigger `compact_context`, DCP, DCP-lite, context pruning, or context compression, call `compact_context` in the next step with the safest allowed scope; do not run shell tests, explain it away, or claim DCP was activated without a tool result. If guards reject the call, report that rejection.",
+        "When the current topic/phase is done, the user changes threads, or old tool output is no longer needed, call `compact_context({ scope: \"closed_phase\", focus: \"short topic/focus\", phaseComplete: true })` once and continue normally.",
+        `If the phase remains active/open, use \`compact_context({ scope: "older_history", keepRecentTokens: ${policy.agentDriven.olderHistoryKeepRecentTokens} })\` to prune older stale history in-flight while a recent raw suffix stays available for the next step.`,
+        "Prefer `mode: \"request_time\"` while the phase is active and context is growing (prunes the next request virtually); use `mode: \"after_turn\"` once the phase is closed (persists compaction after the run).",
+    ].join("\n");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function contentContainsDcpNudge(content) {
+    if (typeof content === "string")
+        return content.includes(DCP_NUDGE_HEADING);
+    if (!Array.isArray(content))
+        return false;
+    return content.some((part) => {
+        if (typeof part === "string")
+            return part.includes(DCP_NUDGE_HEADING);
+        return isRecord(part) && typeof part.text === "string" && part.text.includes(DCP_NUDGE_HEADING);
+    });
+}
+function payloadContainsDcpNudge(payload) {
+    if (!isRecord(payload))
+        return false;
+    if (contentContainsDcpNudge(payload.system))
+        return true;
+    const messages = payload.messages;
+    if (!Array.isArray(messages))
+        return false;
+    return messages.some((message) => isRecord(message) && contentContainsDcpNudge(message.content));
+}
+function appendNudgeToContent(content, nudge) {
+    if (typeof content === "string")
+        return `${content}${nudge}`;
+    if (Array.isArray(content))
+        return [...content, { type: "text", text: nudge.trimStart() }];
+    return nudge.trimStart();
+}
+function injectDcpNudgeIntoAnthropicPayload(payload, nudge) {
+    if (!("system" in payload))
+        return undefined;
+    const system = payload.system;
+    if (typeof system === "string")
+        return { ...payload, system: `${system}${nudge}` };
+    if (Array.isArray(system))
+        return { ...payload, system: [...system, { type: "text", text: nudge.trimStart() }] };
+    if (system === undefined || system === null)
+        return { ...payload, system: [{ type: "text", text: nudge.trimStart() }] };
+    return undefined;
+}
+function injectDcpNudgeIntoOpenAiPayload(payload, nudge) {
+    const messages = payload.messages;
+    if (!Array.isArray(messages))
+        return undefined;
+    const targetIndex = messages.findIndex((message) => {
+        if (!isRecord(message))
+            return false;
+        return message.role === "system" || message.role === "developer";
+    });
+    if (targetIndex === -1) {
+        return { ...payload, messages: [{ role: "system", content: nudge.trimStart() }, ...messages] };
+    }
+    const targetMessage = messages[targetIndex];
+    if (!isRecord(targetMessage))
+        return undefined;
+    const nextMessages = [...messages];
+    nextMessages[targetIndex] = {
+        ...targetMessage,
+        content: appendNudgeToContent(targetMessage.content, nudge),
+    };
+    return { ...payload, messages: nextMessages };
+}
+function injectDcpNudgeIntoProviderPayload(payload, nudge) {
+    if (!isRecord(payload) || payloadContainsDcpNudge(payload))
+        return undefined;
+    return injectDcpNudgeIntoAnthropicPayload(payload, nudge) ?? injectDcpNudgeIntoOpenAiPayload(payload, nudge);
+}
+function rawTokensForContext(ctx) {
+    const entries = ctx.sessionManager.getBranch();
+    return rawTokensSinceLastCompaction(entries);
+}
+function safeRawTokensForContext(ctx) {
+    try {
+        return rawTokensForContext(ctx);
+    }
+    catch {
+        return 0;
+    }
+}
+function isOpenPhase(params) {
+    return params.phaseComplete === false ||
+        params.phaseStatus === "active" ||
+        params.phaseStatus === "open" ||
+        params.phaseStatus === "in_progress";
+}
+function normalizeScope(scope) {
+    return scope === "older_history" ? "older_history" : DEFAULT_COMPACT_CONTEXT_SCOPE;
+}
+/**
+ * Resolve the effective compaction mode for an explicit tool call.
+ *
+ * An explicit `mode` from the caller always wins. When no mode is provided we
+ * promote `request_time` (virtual in-flight pruning) whenever the agent is
+ * still working mid-run and the scope is the safe `older_history` scope — this
+ * shrinks the next provider request immediately instead of deferring to
+ * agent_end. `closed_phase` and idle contexts keep the default `after_turn`
+ * (persisted) mode.
+ */
+function resolveMode(params, scope, ctx) {
+    if (params.mode === "request_time")
+        return "request_time";
+    if (params.mode === "after_turn")
+        return "after_turn";
+    if (scope === "older_history" && hasPendingModelRequest(ctx))
+        return "request_time";
+    return DEFAULT_COMPACT_CONTEXT_MODE;
+}
+function getCompactionPolicy(ctx) {
+    return ctx.settingsManager?.getCompactionPolicy?.() ?? DEFAULT_COMPACTION_POLICY;
+}
+function getRequestCompactionSettings(params, policy) {
+    const scope = normalizeScope(params.scope);
+    if (scope === "older_history") {
+        const keepRecentTokens = normalizeAgentDrivenOlderHistoryKeepRecentTokens(params.keepRecentTokens, policy.agentDriven);
+        return {
+            phaseBoundary: false,
+            scope,
+            keepRecentTokens,
+            minRawTokens: keepRecentTokens + policy.agentDriven.olderHistoryMinCompactableTokens,
+        };
+    }
+    return {
+        phaseBoundary: true,
+        scope,
+        minRawTokens: policy.agentDriven.minRawTokens,
+    };
+}
+function getAutoOlderHistoryRequestSettings(policy) {
+    const keepRecentTokens = policy.agentDriven.olderHistoryKeepRecentTokens;
+    return {
+        phaseBoundary: false,
+        scope: "older_history",
+        keepRecentTokens,
+        minRawTokens: keepRecentTokens + policy.agentDriven.olderHistoryMinCompactableTokens,
+    };
+}
+function isContextAtOrAboveRatio(percent, ratio) {
+    return typeof percent === "number" && Number.isFinite(percent) && percent >= ratio * 100;
+}
+function isContextAtOrAboveTokenLimit(contextTokens, tokenLimit) {
+    return typeof contextTokens === "number" && Number.isFinite(contextTokens) && contextTokens >= tokenLimit;
+}
+function hasPendingModelRequest(ctx) {
+    try {
+        return ctx.hasPendingMessages();
+    }
+    catch {
+        return false;
+    }
+}
+function maybeScheduleAutoOlderHistoryCompaction(ctx, runtime, state, policy, rawTokens, contextTokens, percent, iterationSignal = false) {
+    if (state.request)
+        return false;
+    if (!policy.autoOlderHistory.enabled)
+        return false;
+    const midRun = hasPendingModelRequest(ctx);
+    if (remainingCooldownTurns(state, policy) > 0)
+        return false;
+    const requestSettings = getAutoOlderHistoryRequestSettings(policy);
+    if (rawTokens < requestSettings.minRawTokens)
+        return false;
+    const contextSignal = isContextAtOrAboveRatio(percent, policy.autoOlderHistory.contextLimitRatio);
+    const absoluteContextSignal = isContextAtOrAboveTokenLimit(contextTokens, runtime.config.dcpNudgeMinContextTokens);
+    const rawSignal = rawTokens >= runtime.config.compactionThresholdTokens;
+    if (!contextSignal && !absoluteContextSignal && !rawSignal && !iterationSignal)
+        return false;
+    state.lastAgentDrivenRequestTurn = state.nudgeTurnCount;
+    // Mid-run: prune the next provider request virtually (no session mutation).
+    // Idle: persist compaction after the run for cache-friendly future requests.
+    const mode = midRun ? "request_time" : "after_turn";
+    state.request = { source: "auto", mode, ...requestSettings };
+    if (mode === "request_time")
+        notifyRequestTimeActive(ctx, state.request, rawTokens);
+    else
+        notifyAfterTurnScheduled(ctx, state.request, rawTokens);
+    return true;
+}
+function remainingCooldownTurns(state, policy) {
+    if (state.lastAgentDrivenRequestTurn === null)
+        return 0;
+    const elapsed = Math.max(0, state.nudgeTurnCount - state.lastAgentDrivenRequestTurn);
+    return Math.max(0, policy.agentDriven.cooldownTurns - elapsed);
+}
+function getRequestTimeCompactionSettings(request, policy) {
+    let settings = getManualCompactionSettings(policy.conversation, policy.manual);
+    if (typeof request.keepRecentTokens === "number" && Number.isFinite(request.keepRecentTokens) && request.keepRecentTokens > 0) {
+        settings = { ...settings, keepRecentTokens: request.keepRecentTokens };
+    }
+    return settings;
+}
+function getBranchEntries(ctx) {
+    return ctx.sessionManager.getBranch();
+}
+function createVirtualCompactionEntry(pathEntries, result) {
+    return {
+        type: "compaction",
+        id: REQUEST_TIME_VIRTUAL_COMPACTION_ID,
+        parentId: pathEntries[pathEntries.length - 1]?.id ?? null,
+        timestamp: pathEntries[pathEntries.length - 1]?.timestamp ?? new Date().toISOString(),
+        summary: result.summary,
+        firstKeptEntryId: result.firstKeptEntryId,
+        tokensBefore: result.tokensBefore,
+        details: result.details,
+        fromHook: false,
+    };
+}
+function buildRequestTimePrunedMessages(ctx, request, policy, currentMessages) {
+    const pathEntries = getBranchEntries(ctx);
+    const settings = getRequestTimeCompactionSettings(request, policy);
+    const preparation = prepareCompaction(pathEntries, settings, { phaseBoundary: request.phaseBoundary });
+    if (!preparation)
+        return undefined;
+    const result = compactDcpLite(preparation);
+    const tokensRemoved = result.tokensRemoved ?? 0;
+    if (tokensRemoved <= 0)
+        return undefined;
+    const virtualCompaction = createVirtualCompactionEntry(pathEntries, result);
+    const virtualContext = buildSessionContext([...pathEntries, virtualCompaction]);
+    if (virtualContext.messages.length === 0)
+        return undefined;
+    const originalTokens = estimateContextTokens(currentMessages).tokens;
+    const prunedTokens = estimateContextTokens(virtualContext.messages).tokens;
+    if (prunedTokens >= originalTokens)
+        return undefined;
+    return { messages: virtualContext.messages, tokensRemoved, originalTokens, prunedTokens };
+}
+function notifyRequestTimeActive(ctx, request, rawTokens) {
+    if (!ctx.hasUI)
+        return;
+    const sourceText = request.source === "auto" ? "auto" : "explicit tool";
+    const rawText = typeof rawTokens === "number" && Number.isFinite(rawTokens)
+        ? `; raw ~${formatTokenCount(rawTokens)}`
+        : "";
+    const keepText = typeof request.keepRecentTokens === "number" && Number.isFinite(request.keepRecentTokens)
+        ? `; keep recent ~${formatTokenCount(request.keepRecentTokens)}`
+        : "";
+    ctx.ui?.notify(`DCP-lite request-time pruning active — ${sourceText} ${request.scope}; applies before the current-turn continuation provider request${rawText}${keepText}`, "info");
+}
+function notifyRequestTimeApplied(ctx, result) {
+    if (!ctx.hasUI)
+        return;
+    const removedTokens = Math.max(0, result.originalTokens - result.prunedTokens);
+    ctx.ui?.notify(`DCP-lite request-time pruning applied — before ~${formatTokenCount(result.originalTokens)}, after ~${formatTokenCount(result.prunedTokens)}, removed ~${formatTokenCount(removedTokens)} tokens`, "info");
+}
+function notifyRequestTimeSkip(ctx, reason) {
+    if (ctx.hasUI)
+        ctx.ui?.notify(`DCP-lite request-time pruning skipped — ${reason}`, "info");
+}
+function notifyAfterTurnScheduled(ctx, request, rawTokens) {
+    if (!ctx.hasUI)
+        return;
+    const sourceText = request.source === "auto" ? "auto" : "explicit tool";
+    const rawText = typeof rawTokens === "number" && Number.isFinite(rawTokens)
+        ? `; raw ~${formatTokenCount(rawTokens)}`
+        : "";
+    const keepText = typeof request.keepRecentTokens === "number" && Number.isFinite(request.keepRecentTokens)
+        ? `; keep recent ~${formatTokenCount(request.keepRecentTokens)}`
+        : "";
+    ctx.ui?.notify(`DCP-lite after-turn compaction scheduled — ${sourceText} ${request.scope}; persists after this run for cache-friendly future requests${rawText}${keepText}`, "info");
+}
+function registerAgentCompactionTool(ext, runtime, state) {
+    ext.registerTool(defineTool({
+        name: COMPACT_CONTEXT_TOOL_NAME,
+        label: "Compact context",
+        description: "Request Spectral DCP-lite context compaction. " +
+            "Use closed_phase after a completed phase/topic boundary, or older_history to compact stale older history while preserving recent raw context. " +
+            "Mid-run (agent still working) the default is virtual request_time pruning that shrinks the next provider request without mutating session history; when idle or the phase is closed, persisted after_turn compaction runs after this run.",
+        promptSnippet: "compact_context: call this tool when DCP/DCP-lite/context pruning is explicitly requested; mid-run it prunes the next provider request virtually (request_time), or persists after-turn compaction for a closed phase / idle agent.",
+        promptGuidelines: [
+            `If the user explicitly asks to run, trigger, or activate \`${COMPACT_CONTEXT_TOOL_NAME}\`, DCP, DCP-lite, context pruning, or context compression, call \`${COMPACT_CONTEXT_TOOL_NAME}\` immediately with the safest allowed scope; do not run shell tests, explain it away, or claim activation without this tool result. If guards reject it, report the rejection.`,
+            `Use \`${COMPACT_CONTEXT_TOOL_NAME}\` with scope=closed_phase only after a major phase/topic is complete and old raw tool output is no longer needed.`,
+            `Use scope=older_history when the current phase is still active but older stale history can be summarized while a recent raw suffix stays available.`,
+            `Default mode: while the agent is mid-run with an active phase, request_time prunes the next provider request virtually (no session mutation); after_turn persists compaction after the run. Prefer request_time while the phase is active and context is growing, after_turn once the phase is closed.`,
+            `Do not call \`${COMPACT_CONTEXT_TOOL_NAME}\` before extracting raw details needed for the next response.`,
+        ],
+        parameters: COMPACT_CONTEXT_TOOL_PARAMS,
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            runtime.ensureConfig(ctx.cwd);
+            const policy = getCompactionPolicy(ctx);
+            if (runtime.config.passive === true) {
+                return {
+                    content: [{ type: "text", text: "DCP-lite compaction is disabled because observational memory is in passive mode." }],
+                    details: { status: "passive" },
+                };
+            }
+            if (!policy.agentDriven.enabled) {
+                return {
+                    content: [{ type: "text", text: "DCP-lite compaction is disabled by compaction.agentDriven.enabled=false." }],
+                    details: { status: "disabled" },
+                };
+            }
+            const requestSettings = getRequestCompactionSettings(params, policy);
+            const mode = resolveMode(params, requestSettings.scope, ctx);
+            if (requestSettings.scope === "closed_phase" && isOpenPhase(params)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "DCP-lite compaction not activated because the current phase is marked active/open and closed_phase scope requires a complete/closed phase. Use older_history only when preserving a recent raw suffix is sufficient.",
+                        }],
+                    details: { status: "phase_open" },
+                };
+            }
+            if (runtime.compactInFlight) {
+                return {
+                    content: [{ type: "text", text: "DCP-lite compaction not activated because compaction is already in flight." }],
+                    details: { status: "in_flight" },
+                };
+            }
+            const replacingAutoRequest = state.request?.source === "auto";
+            if (state.request && !replacingAutoRequest) {
+                const pendingText = state.request.mode === "after_turn"
+                    ? "after this agent run"
+                    : "for the current-turn continuation provider request";
+                return {
+                    content: [{ type: "text", text: `DCP-lite compaction is already ${state.request.mode === "after_turn" ? "scheduled" : "active"} ${pendingText}.` }],
+                    details: { status: "pending" },
+                };
+            }
+            const cooldownTurns = replacingAutoRequest ? 0 : remainingCooldownTurns(state, policy);
+            if (cooldownTurns > 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `DCP-lite compaction not activated because a recent agent-driven request is cooling down. Wait ${cooldownTurns} more turn${cooldownTurns === 1 ? "" : "s"}.`,
+                        }],
+                    details: { status: "cooldown", cooldownTurns },
+                };
+            }
+            const rawTokens = safeRawTokensForContext(ctx);
+            if (rawTokens < requestSettings.minRawTokens) {
+                const suffixText = requestSettings.keepRecentTokens
+                    ? ` while preserving ~${requestSettings.keepRecentTokens.toLocaleString()} recent raw tokens`
+                    : "";
+                return {
+                    content: [{
+                            type: "text",
+                            text: `DCP-lite compaction not activated because there are only ~${rawTokens.toLocaleString()} raw tokens since the last compaction; wait until at least ~${requestSettings.minRawTokens.toLocaleString()} raw tokens accumulate${suffixText}.`,
+                        }],
+                    details: {
+                        status: "insufficient_material",
+                        rawTokens,
+                        minRawTokens: requestSettings.minRawTokens,
+                        scope: requestSettings.scope,
+                        keepRecentTokens: requestSettings.keepRecentTokens,
+                    },
+                };
+            }
+            const customInstructions = buildCustomInstructions(params);
+            state.lastAgentDrivenRequestTurn = state.nudgeTurnCount;
+            state.request = { source: "tool", mode, customInstructions, ...requestSettings };
+            if (mode === "request_time")
+                notifyRequestTimeActive(ctx, state.request, rawTokens);
+            const focusText = customInstructions ? ` Focus: ${customInstructions}` : "";
+            const scopeText = requestSettings.scope === "older_history" ? " Scope: older_history." : "";
+            const modeText = mode === "after_turn"
+                ? "DCP-lite after-turn compaction scheduled after this agent run for cache-friendly future requests."
+                : "DCP-lite request-time pruning active for the current-turn continuation provider request.";
+            const actionText = mode === "after_turn"
+                ? "Spectral will persist the compaction once the agent is idle."
+                : "Continue normally; Spectral will build this continuation payload from a virtual DCP-lite summary plus the kept raw suffix without mutating session history.";
+            return {
+                content: [{
+                        type: "text",
+                        text: `${modeText}${scopeText}${focusText} ${actionText}`,
+                    }],
+                details: {
+                    status: mode === "request_time" ? "active" : "scheduled",
+                    mode,
+                    customInstructions,
+                    rawTokens,
+                    scope: requestSettings.scope,
+                    keepRecentTokens: requestSettings.keepRecentTokens,
+                },
+            };
+        },
+    }));
+}
+export function registerCompactContextTool(ext, runtime) {
+    const state = getState(runtime);
+    registerAgentCompactionTool(ext, runtime, state);
+    /** Wrap a handler so debugLog calls inside it (and its helpers) are emitted when debugLog is on. */
+    const withDebug = (handler) => (event, ctx) => {
+        runtime.ensureConfig(ctx.cwd);
+        return withDebugLogContext({ enabled: runtime.config.debugLog === true, cwd: ctx.cwd }, () => handler(event, ctx));
+    };
+    ext.on("before_agent_start", withDebug((_event, ctx) => {
+        runtime.ensureConfig(ctx.cwd);
+        if (runtime.config.passive === true)
+            return;
+        const policy = getCompactionPolicy(ctx);
+        if (!policy.agentDriven.enabled)
+            return;
+        state.providerRequestCount = 0;
+        state.lastInRunNudgeRequest = 0;
+        state.nudgeTurnCount += 1;
+        let rawTokens = 0;
+        try {
+            rawTokens = rawTokensForContext(ctx);
+        }
+        catch {
+            rawTokens = 0;
+        }
+        const usage = ctx.getContextUsage();
+        const contextTokens = usage?.tokens;
+        const percent = usage?.percent;
+        const minRawTokens = runtime.config.dcpNudgeMinRawTokens;
+        const minContextTokens = runtime.config.dcpNudgeMinContextTokens;
+        const minPercent = runtime.config.dcpNudgeContextPercent;
+        const turnInterval = runtime.config.dcpNudgeTurnInterval;
+        const turnsSinceNudge = state.nudgeTurnCount - state.lastNudgeTurn;
+        const rawSignal = rawTokens >= minRawTokens;
+        const absoluteContextSignal = isContextAtOrAboveTokenLimit(contextTokens, minContextTokens);
+        const percentSignal = typeof percent === "number" && Number.isFinite(percent) && percent >= minPercent;
+        const intervalSignal = turnsSinceNudge >= turnInterval && rawTokens >= Math.floor(minRawTokens / 2);
+        maybeScheduleAutoOlderHistoryCompaction(ctx, runtime, state, policy, rawTokens, contextTokens, percent);
+        if (!rawSignal && !absoluteContextSignal && !percentSignal && !intervalSignal)
+            return;
+        state.lastNudgeTurn = state.nudgeTurnCount;
+        const nudge = buildDcpNudge(rawTokens, contextTokens, percent, policy);
+        return { systemPrompt: `${_event.systemPrompt}${nudge}` };
+    }));
+    ext.on("context", withDebug((_event, ctx) => {
+        runtime.ensureConfig(ctx.cwd);
+        if (runtime.config.passive === true)
+            return;
+        const policy = getCompactionPolicy(ctx);
+        if (!policy.agentDriven.enabled)
+            return;
+        // 1. Explicit request (agent-driven tool call or turn-start auto-schedule).
+        //    These set state.request before this context event fires, so pruning
+        //    applies to the current provider request with no lag.
+        const request = state.request;
+        if (request && request.mode === "request_time") {
+            state.request = null;
+            if (runtime.compactInFlight) {
+                notifyRequestTimeSkip(ctx, "another compaction is already in flight");
+                return;
+            }
+            const rawTokens = safeRawTokensForContext(ctx);
+            if (rawTokens < request.minRawTokens) {
+                notifyRequestTimeSkip(ctx, "not enough raw material since the last compaction");
+                return;
+            }
+            const pruned = buildRequestTimePrunedMessages(ctx, request, policy, _event.messages);
+            if (!pruned) {
+                notifyRequestTimeSkip(ctx, "virtual summary would not shrink the next request");
+                return;
+            }
+            debugLog("compact_context.request_time.explicit", {
+                rawTokens,
+                originalTokens: pruned.originalTokens,
+                prunedTokens: pruned.prunedTokens,
+                tokensRemoved: pruned.tokensRemoved,
+            });
+            notifyRequestTimeApplied(ctx, pruned);
+            return { messages: pruned.messages };
+        }
+        // 2. Auto request_time pruning — mid-run, no explicit request.
+        //    Decides AND prunes in the same handler invocation. This is critical:
+        //    before_provider_request fires AFTER this context event within the
+        //    same provider request cycle, so scheduling there would always lag by
+        //    one full request (the oversized request would already be sent).
+        //    Virtual pruning is non-mutating, so we skip the agent-driven cooldown
+        //    (that guards the expensive persisted after_turn compaction only).
+        if (!hasPendingModelRequest(ctx))
+            return;
+        if (runtime.compactInFlight)
+            return;
+        if (!policy.autoOlderHistory.enabled)
+            return;
+        const autoSettings = getAutoOlderHistoryRequestSettings(policy);
+        const autoRawTokens = safeRawTokensForContext(ctx);
+        if (autoRawTokens < autoSettings.minRawTokens)
+            return;
+        const autoUsage = ctx.getContextUsage();
+        const autoContextTokens = autoUsage?.tokens;
+        const autoPercent = autoUsage?.percent;
+        const autoContextSignal = isContextAtOrAboveRatio(autoPercent, policy.autoOlderHistory.contextLimitRatio);
+        const autoAbsoluteSignal = isContextAtOrAboveTokenLimit(autoContextTokens, runtime.config.dcpNudgeMinContextTokens);
+        const autoRawSignal = autoRawTokens >= runtime.config.compactionThresholdTokens;
+        if (!autoContextSignal && !autoAbsoluteSignal && !autoRawSignal)
+            return;
+        const autoRequest = { source: "auto", mode: "request_time", ...autoSettings };
+        const autoPruned = buildRequestTimePrunedMessages(ctx, autoRequest, policy, _event.messages);
+        if (!autoPruned) {
+            debugLog("compact_context.request_time.auto_skip", {
+                rawTokens: autoRawTokens,
+                contextTokens: autoContextTokens ?? null,
+                percent: autoPercent ?? null,
+                reason: "virtual summary would not shrink the next request",
+            });
+            return;
+        }
+        debugLog("compact_context.request_time.auto", {
+            rawTokens: autoRawTokens,
+            contextTokens: autoContextTokens ?? null,
+            percent: autoPercent ?? null,
+            originalTokens: autoPruned.originalTokens,
+            prunedTokens: autoPruned.prunedTokens,
+            tokensRemoved: autoPruned.tokensRemoved,
+        });
+        notifyRequestTimeApplied(ctx, autoPruned);
+        return { messages: autoPruned.messages };
+    }));
+    ext.on("before_provider_request", withDebug((_event, ctx) => {
+        runtime.ensureConfig(ctx.cwd);
+        if (runtime.config.passive === true)
+            return;
+        const policy = getCompactionPolicy(ctx);
+        if (!policy.agentDriven.enabled)
+            return;
+        state.providerRequestCount += 1;
+        const rawTokens = safeRawTokensForContext(ctx);
+        const usage = ctx.getContextUsage();
+        const contextTokens = usage?.tokens;
+        const percent = usage?.percent;
+        const minRawTokens = runtime.config.dcpNudgeMinRawTokens;
+        const minContextTokens = runtime.config.dcpNudgeMinContextTokens;
+        const minPercent = runtime.config.dcpNudgeContextPercent;
+        const iterationThreshold = runtime.config.dcpInRunNudgeIterationThreshold;
+        const frequency = runtime.config.dcpInRunNudgeFrequency;
+        const rawSignal = rawTokens >= minRawTokens;
+        const absoluteContextSignal = isContextAtOrAboveTokenLimit(contextTokens, minContextTokens);
+        const percentSignal = typeof percent === "number" && Number.isFinite(percent) && percent >= minPercent;
+        const iterationSignal = state.providerRequestCount >= iterationThreshold;
+        const frequencyReady = state.lastInRunNudgeRequest === 0 ||
+            state.providerRequestCount - state.lastInRunNudgeRequest >= frequency;
+        debugLog("compact_context.before_provider_request", {
+            providerRequestCount: state.providerRequestCount,
+            rawTokens,
+            contextTokens: contextTokens ?? null,
+            percent: percent ?? null,
+            rawSignal,
+            absoluteContextSignal,
+            percentSignal,
+            iterationSignal,
+            frequencyReady,
+        });
+        // NOTE: maybeScheduleAutoOlderHistoryCompaction is intentionally NOT called
+        // here. This event fires AFTER the context event within the same provider
+        // request cycle, so any state.request set here would only be visible to
+        // the context event on the NEXT request — a one-request lag that lets the
+        // oversized request through unpruned. Auto request_time pruning is now
+        // decided inline in the context event handler (no lag).
+        if ((!rawSignal && !absoluteContextSignal && !percentSignal && !iterationSignal) || !frequencyReady)
+            return;
+        if (payloadContainsDcpNudge(_event.payload)) {
+            state.lastInRunNudgeRequest = state.providerRequestCount;
+            return;
+        }
+        const nudge = buildDcpNudge(rawTokens, contextTokens, percent, policy, state.providerRequestCount);
+        const payload = injectDcpNudgeIntoProviderPayload(_event.payload, nudge);
+        if (payload === undefined)
+            return;
+        state.lastInRunNudgeRequest = state.providerRequestCount;
+        return payload;
+    }));
+    ext.on("agent_end", withDebug((_event, ctx) => {
+        state.providerRequestCount = 0;
+        state.lastInRunNudgeRequest = 0;
+        const request = state.request;
+        if (!request || request.mode !== "after_turn")
+            return;
+        state.request = null;
+        runtime.ensureConfig(ctx.cwd);
+        if (runtime.config.passive === true)
+            return;
+        if (runtime.compactInFlight) {
+            if (ctx.hasUI)
+                ctx.ui?.notify("DCP-lite compaction skipped — another compaction is already in flight", "info");
+            return;
+        }
+        const rawTokens = safeRawTokensForContext(ctx);
+        if (rawTokens < request.minRawTokens) {
+            if (ctx.hasUI)
+                ctx.ui?.notify("DCP-lite compaction skipped — not enough raw material since last compaction", "info");
+            return;
+        }
+        const hasUI = ctx.hasUI;
+        const ui = ctx.ui;
+        runtime.compactInFlight = true;
+        setTimeout(async () => {
+            if (runtime.observerPromise) {
+                try {
+                    await runtime.observerPromise;
+                }
+                catch {
+                    // errors already surfaced via launchObserverTask
+                }
+            }
+            try {
+                if (!ctx.isIdle()) {
+                    runtime.compactInFlight = false;
+                    state.request = request;
+                    if (hasUI)
+                        ui?.notify("DCP-lite compaction deferred — agent is not idle yet", "info");
+                    return;
+                }
+                const currentRawTokens = safeRawTokensForContext(ctx);
+                if (currentRawTokens < request.minRawTokens) {
+                    runtime.compactInFlight = false;
+                    if (hasUI)
+                        ui?.notify("DCP-lite compaction skipped — not enough raw material since last compaction", "info");
+                    return;
+                }
+                if (hasUI && request.source === "auto") {
+                    ui?.notify("DCP-lite auto older-history compaction starting", "info");
+                }
+                ctx.compact({
+                    customInstructions: request.customInstructions,
+                    phaseBoundary: request.phaseBoundary,
+                    keepRecentTokens: request.keepRecentTokens,
+                    memoryHookMode: "skip",
+                    onComplete: (result) => {
+                        runtime.compactInFlight = false;
+                        if (!hasUI)
+                            return;
+                        if (result.skipped) {
+                            ui?.notify(`DCP-lite compaction skipped — ${result.message ?? "summary would not shrink context"}`, "warning");
+                            return;
+                        }
+                        ui?.notify("DCP-lite compaction complete", "info");
+                    },
+                    onError: (error) => {
+                        runtime.compactInFlight = false;
+                        if (error.message === "Compaction cancelled" ||
+                            error.message === "Compaction already in progress") {
+                            return;
+                        }
+                        if (hasUI)
+                            ui?.notify(`DCP-lite compaction failed: ${error.message}`, "error");
+                    },
+                });
+            }
+            catch (error) {
+                runtime.compactInFlight = false;
+                const msg = error instanceof Error ? error.message : String(error);
+                if (hasUI)
+                    ui?.notify(`DCP-lite compaction threw: ${msg}`, "error");
+            }
+        }, 0);
+    }));
+}