gsd-pi 2.76.0 → 2.77.0-dev.538325aea

package/packages/gsd-agent-core/dist/compaction-orchestrator.js

@@ -0,0 +1,338 @@
+/**
+ * CompactionOrchestrator - Manages manual and automatic context compaction.
+ *
+ * Handles:
+ * - Manual compaction (user-triggered /compact)
+ * - Auto-compaction when context exceeds threshold
+ * - Overflow recovery when LLM returns context overflow errors
+ * - Extension integration for custom compaction providers
+ * - Branch summarization abort coordination
+ */
+import { isContextOverflow } from "@gsd/pi-ai";
+import { calculateContextTokens, compact, estimateContextTokens, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { getLatestCompactionEntry } from "@gsd/pi-coding-agent";
+/** Extract a human-readable error message from an unknown thrown value. */
+function getErrorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+export class CompactionOrchestrator {
+    constructor(_deps) {
+        this._deps = _deps;
+        this._compactionAbortController = undefined;
+        this._autoCompactionAbortController = undefined;
+        this._overflowRecoveryAttempted = false;
+        this._branchSummaryAbortController = undefined;
+    }
+    /** Whether compaction or branch summarization is currently running */
+    get isCompacting() {
+        return (this._autoCompactionAbortController !== undefined ||
+            this._compactionAbortController !== undefined ||
+            this._branchSummaryAbortController !== undefined);
+    }
+    /** Reset overflow recovery flag (called when a new user message starts) */
+    resetOverflowRecovery() {
+        this._overflowRecoveryAttempted = false;
+    }
+    /** Mark overflow recovery as not needed (called on successful assistant response) */
+    clearOverflowRecovery() {
+        this._overflowRecoveryAttempted = false;
+    }
+    /** Get/set the branch summary abort controller (used by navigateTree) */
+    get branchSummaryAbortController() {
+        return this._branchSummaryAbortController;
+    }
+    set branchSummaryAbortController(controller) {
+        this._branchSummaryAbortController = controller;
+    }
+    /**
+     * Manually compact the session context.
+     * Aborts current agent operation first.
+     * @param customInstructions Optional instructions for the compaction summary
+     */
+    async compact(customInstructions) {
+        this._deps.disconnectFromAgent();
+        await this._deps.abort();
+        this._compactionAbortController = new AbortController();
+        try {
+            const model = this._deps.getModel();
+            if (!model) {
+                throw new Error("No model selected");
+            }
+            if (!this._deps.modelRegistry.isProviderRequestReady(model.provider)) {
+                throw new Error(`No API key for ${model.provider}`);
+            }
+            // undefined for providers without API keys (e.g. external CLI) — stripped at streamSimple boundary.
+            const authResult = await this._deps.modelRegistry.getApiKeyAndHeaders(model);
+            const apiKey = authResult.ok ? authResult.apiKey : undefined;
+            const pathEntries = this._deps.sessionManager.getBranch();
+            const settings = this._deps.settingsManager.getCompactionSettings();
+            const preparation = prepareCompaction(pathEntries, settings);
+            if (!preparation) {
+                const lastEntry = pathEntries[pathEntries.length - 1];
+                if (lastEntry?.type === "compaction") {
+                    throw new Error("Already compacted");
+                }
+                throw new Error("Nothing to compact (session too small)");
+            }
+            let extensionCompaction;
+            let fromExtension = false;
+            const extensionRunner = this._deps.getExtensionRunner();
+            if (extensionRunner?.hasHandlers("session_before_compact")) {
+                const result = (await extensionRunner.emit({
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
+                    customInstructions,
+                    signal: this._compactionAbortController.signal,
+                }));
+                if (result?.cancel) {
+                    throw new Error("Compaction cancelled");
+                }
+                if (result?.compaction) {
+                    extensionCompaction = result.compaction;
+                    fromExtension = true;
+                }
+            }
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let details;
+            if (extensionCompaction) {
+                summary = extensionCompaction.summary;
+                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
+                tokensBefore = extensionCompaction.tokensBefore;
+                details = extensionCompaction.details;
+            }
+            else {
+                const result = await compact(preparation, model, apiKey, customInstructions, this._compactionAbortController.signal);
+                summary = result.summary;
+                firstKeptEntryId = result.firstKeptEntryId;
+                tokensBefore = result.tokensBefore;
+                details = result.details;
+            }
+            if (this._compactionAbortController.signal.aborted) {
+                throw new Error("Compaction cancelled");
+            }
+            this._deps.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
+            const newEntries = this._deps.sessionManager.getEntries();
+            const sessionContext = this._deps.sessionManager.buildSessionContext();
+            this._deps.agent.state.messages = sessionContext.messages;
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (extensionRunner && savedCompactionEntry) {
+                await extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
+                    fromExtension,
+                });
+            }
+            return { summary, firstKeptEntryId, tokensBefore, details };
+        }
+        finally {
+            this._compactionAbortController = undefined;
+            this._deps.reconnectToAgent();
+        }
+    }
+    /** Cancel in-progress compaction (manual or auto) */
+    abortCompaction() {
+        this._compactionAbortController?.abort();
+        this._autoCompactionAbortController?.abort();
+    }
+    /** Cancel in-progress branch summarization */
+    abortBranchSummary() {
+        this._branchSummaryAbortController?.abort();
+    }
+    /**
+     * Check if compaction is needed and run it.
+     * Called after agent_end and before prompt submission.
+     *
+     * Two cases:
+     * 1. Overflow: LLM returned context overflow error, remove error message, compact, auto-retry
+     * 2. Threshold: Context over threshold, compact, NO auto-retry
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     */
+    async checkCompaction(assistantMessage, skipAbortedCheck = true) {
+        const settings = this._deps.settingsManager.getCompactionSettings();
+        if (!settings.enabled)
+            return;
+        if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
+            return;
+        const model = this._deps.getModel();
+        const contextWindow = model?.contextWindow ?? 0;
+        const sameModel = model && assistantMessage.provider === model.provider && assistantMessage.model === model.id;
+        const branchEntries = this._deps.sessionManager.getBranch();
+        const compactionEntry = getLatestCompactionEntry(branchEntries);
+        const assistantIsFromBeforeCompaction = compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();
+        if (assistantIsFromBeforeCompaction)
+            return;
+        // Case 1: Overflow - LLM returned context overflow error
+        if (sameModel && isContextOverflow(assistantMessage, contextWindow)) {
+            if (this._overflowRecoveryAttempted) {
+                this._deps.emit({
+                    type: "auto_compaction_end",
+                    result: undefined,
+                    aborted: false,
+                    willRetry: false,
+                    errorMessage: "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.",
+                });
+                return;
+            }
+            this._overflowRecoveryAttempted = true;
+            const messages = this._deps.agent.state.messages;
+            if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
+                this._deps.agent.state.messages = messages.slice(0, -1);
+            }
+            await this._runAutoCompaction("overflow", true);
+            return;
+        }
+        // Case 2: Threshold - context is getting large
+        let contextTokens;
+        if (assistantMessage.stopReason === "error") {
+            const messages = this._deps.agent.state.messages;
+            const estimate = estimateContextTokens(messages);
+            if (estimate.lastUsageIndex === null)
+                return;
+            const usageMsg = messages[estimate.lastUsageIndex];
+            if (compactionEntry &&
+                usageMsg.role === "assistant" &&
+                usageMsg.timestamp <= new Date(compactionEntry.timestamp).getTime()) {
+                return;
+            }
+            contextTokens = estimate.tokens;
+        }
+        else {
+            contextTokens = calculateContextTokens(assistantMessage.usage);
+        }
+        if (shouldCompact(contextTokens, contextWindow, settings)) {
+            await this._runAutoCompaction("threshold", false);
+        }
+    }
+    /** Toggle auto-compaction setting */
+    setAutoCompactionEnabled(enabled) {
+        this._deps.settingsManager.setCompactionEnabled(enabled);
+    }
+    /** Whether auto-compaction is enabled */
+    get autoCompactionEnabled() {
+        return this._deps.settingsManager.getCompactionEnabled();
+    }
+    // =========================================================================
+    // Private helpers
+    // =========================================================================
+    async _runAutoCompaction(reason, willRetry) {
+        const settings = this._deps.settingsManager.getCompactionSettings();
+        this._deps.emit({ type: "auto_compaction_start", reason });
+        this._autoCompactionAbortController = new AbortController();
+        try {
+            const model = this._deps.getModel();
+            if (!model) {
+                this._deps.emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                return;
+            }
+            if (!this._deps.modelRegistry.isProviderRequestReady(model.provider)) {
+                this._deps.emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                return;
+            }
+            // undefined for providers without API keys (e.g. external CLI) — stripped at streamSimple boundary.
+            const authResult = await this._deps.modelRegistry.getApiKeyAndHeaders(model);
+            const apiKey = authResult.ok ? authResult.apiKey : undefined;
+            const pathEntries = this._deps.sessionManager.getBranch();
+            const preparation = prepareCompaction(pathEntries, settings);
+            if (!preparation) {
+                this._deps.emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                return;
+            }
+            let extensionCompaction;
+            let fromExtension = false;
+            const extensionRunner = this._deps.getExtensionRunner();
+            if (extensionRunner?.hasHandlers("session_before_compact")) {
+                const extensionResult = (await extensionRunner.emit({
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
+                    customInstructions: undefined,
+                    signal: this._autoCompactionAbortController.signal,
+                }));
+                if (extensionResult?.cancel) {
+                    this._deps.emit({
+                        type: "auto_compaction_end",
+                        result: undefined,
+                        aborted: true,
+                        willRetry: false,
+                    });
+                    return;
+                }
+                if (extensionResult?.compaction) {
+                    extensionCompaction = extensionResult.compaction;
+                    fromExtension = true;
+                }
+            }
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let details;
+            if (extensionCompaction) {
+                summary = extensionCompaction.summary;
+                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
+                tokensBefore = extensionCompaction.tokensBefore;
+                details = extensionCompaction.details;
+            }
+            else {
+                const compactResult = await compact(preparation, model, apiKey, undefined, this._autoCompactionAbortController.signal);
+                summary = compactResult.summary;
+                firstKeptEntryId = compactResult.firstKeptEntryId;
+                tokensBefore = compactResult.tokensBefore;
+                details = compactResult.details;
+            }
+            if (this._autoCompactionAbortController.signal.aborted) {
+                this._deps.emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
+                return;
+            }
+            this._deps.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
+            const newEntries = this._deps.sessionManager.getEntries();
+            const sessionContext = this._deps.sessionManager.buildSessionContext();
+            this._deps.agent.state.messages = sessionContext.messages;
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (extensionRunner && savedCompactionEntry) {
+                await extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
+                    fromExtension,
+                });
+            }
+            const result = { summary, firstKeptEntryId, tokensBefore, details };
+            this._deps.emit({ type: "auto_compaction_end", result, aborted: false, willRetry });
+            if (willRetry) {
+                const messages = this._deps.agent.state.messages;
+                const lastMsg = messages[messages.length - 1];
+                if (lastMsg?.role === "assistant" && lastMsg.stopReason === "error") {
+                    this._deps.agent.state.messages = messages.slice(0, -1);
+                }
+                setTimeout(() => {
+                    this._deps.agent.continue().catch(() => { });
+                }, 100);
+            }
+            else if (this._deps.agent.hasQueuedMessages()) {
+                setTimeout(() => {
+                    this._deps.agent.continue().catch(() => { });
+                }, 100);
+            }
+        }
+        catch (error) {
+            const errorMessage = getErrorMessage(error);
+            this._deps.emit({
+                type: "auto_compaction_end",
+                result: undefined,
+                aborted: false,
+                willRetry: false,
+                errorMessage: reason === "overflow"
+                    ? `Context overflow recovery failed: ${errorMessage}`
+                    : `Auto-compaction failed: ${errorMessage}`,
+            });
+        }
+        finally {
+            this._autoCompactionAbortController = undefined;
+        }
+    }
+}
+//# sourceMappingURL=compaction-orchestrator.js.map

package/packages/gsd-agent-core/dist/compaction-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-orchestrator.js","sourceRoot":"","sources":["../src/compaction-orchestrator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * CompactionOrchestrator - Manages manual and automatic context compaction.\n *\n * Handles:\n * - Manual compaction (user-triggered /compact)\n * - Auto-compaction when context exceeds threshold\n * - Overflow recovery when LLM returns context overflow errors\n * - Extension integration for custom compaction providers\n * - Branch summarization abort coordination\n */\n\nimport type { Agent } from \"@gsd/pi-agent-core\";\nimport type { Api, AssistantMessage, Model } from \"@gsd/pi-ai\";\nimport { isContextOverflow } from \"@gsd/pi-ai\";\nimport {\n\ttype CompactionResult,\n\tcalculateContextTokens,\n\tcompact,\n\testimateContextTokens,\n\tprepareCompaction,\n\tshouldCompact,\n} from \"./compaction/index.js\";\nimport type { ExtensionRunner } from \"@gsd/agent-types\";\nimport type { ModelRegistry } from \"@gsd/agent-types\";\nimport { getLatestCompactionEntry } from \"@gsd/pi-coding-agent\";\nimport type { CompactionEntry, SessionManager } from \"@gsd/agent-types\";\nimport type { SettingsManager } from \"@gsd/agent-types\";\nimport type { AgentSessionEvent } from \"./agent-session.js\";\n\n// Local shims for types/functions absent from @gsd/pi-coding-agent 0.67.2 public API.\n// Phase 09 moves these to @gsd/agent-types or resolves via upstream PR.\n\n/** Result returned by session_before_compact extension handlers. */\ninterface SessionBeforeCompactResult {\n\tcancel?: boolean;\n\tcompaction?: CompactionResult;\n}\n\n/** Extract a human-readable error message from an unknown thrown value. */\nfunction getErrorMessage(e: unknown): string {\n\treturn e instanceof Error ? e.message : String(e);\n}\n\n/** Extended ModelRegistry with GSD provider readiness check. */\ninterface ModelRegistryWithReadiness extends ModelRegistry {\n\tisProviderRequestReady(provider: string): boolean;\n\tgetApiKeyAndHeaders(model: import(\"@gsd/pi-ai\").Model<import(\"@gsd/pi-ai\").Api>): Promise<\n\t\t{ ok: true; apiKey?: string; headers?: Record<string, string> } | { ok: false; error: string }\n\t>;\n}\n\n/** Dependencies injected from AgentSession into CompactionOrchestrator */\nexport interface CompactionOrchestratorDeps {\n\treadonly agent: Agent;\n\treadonly sessionManager: SessionManager;\n\treadonly settingsManager: SettingsManager;\n\treadonly modelRegistry: ModelRegistryWithReadiness;\n\tgetModel: () => Model<Api> | undefined;\n\tgetSessionId: () => string;\n\tgetExtensionRunner: () => ExtensionRunner | undefined;\n\temit: (event: AgentSessionEvent) => void;\n\tdisconnectFromAgent: () => void;\n\treconnectToAgent: () => void;\n\tabort: () => Promise<void>;\n}\n\nexport class CompactionOrchestrator {\n\tprivate _compactionAbortController: AbortController | undefined = undefined;\n\tprivate _autoCompactionAbortController: AbortController | undefined = undefined;\n\tprivate _overflowRecoveryAttempted = false;\n\tprivate _branchSummaryAbortController: AbortController | undefined = undefined;\n\n\tconstructor(private readonly _deps: CompactionOrchestratorDeps) {}\n\n\t/** Whether compaction or branch summarization is currently running */\n\tget isCompacting(): boolean {\n\t\treturn (\n\t\t\tthis._autoCompactionAbortController !== undefined ||\n\t\t\tthis._compactionAbortController !== undefined ||\n\t\t\tthis._branchSummaryAbortController !== undefined\n\t\t);\n\t}\n\n\t/** Reset overflow recovery flag (called when a new user message starts) */\n\tresetOverflowRecovery(): void {\n\t\tthis._overflowRecoveryAttempted = false;\n\t}\n\n\t/** Mark overflow recovery as not needed (called on successful assistant response) */\n\tclearOverflowRecovery(): void {\n\t\tthis._overflowRecoveryAttempted = false;\n\t}\n\n\t/** Get/set the branch summary abort controller (used by navigateTree) */\n\tget branchSummaryAbortController(): AbortController | undefined {\n\t\treturn this._branchSummaryAbortController;\n\t}\n\tset branchSummaryAbortController(controller: AbortController | undefined) {\n\t\tthis._branchSummaryAbortController = controller;\n\t}\n\n\t/**\n\t * Manually compact the session context.\n\t * Aborts current agent operation first.\n\t * @param customInstructions Optional instructions for the compaction summary\n\t */\n\tasync compact(customInstructions?: string): Promise<CompactionResult> {\n\t\tthis._deps.disconnectFromAgent();\n\t\tawait this._deps.abort();\n\t\tthis._compactionAbortController = new AbortController();\n\n\t\ttry {\n\t\t\tconst model = this._deps.getModel();\n\t\t\tif (!model) {\n\t\t\t\tthrow new Error(\"No model selected\");\n\t\t\t}\n\n\t\t\tif (!this._deps.modelRegistry.isProviderRequestReady(model.provider)) {\n\t\t\t\tthrow new Error(`No API key for ${model.provider}`);\n\t\t\t}\n\t\t\t// undefined for providers without API keys (e.g. external CLI) — stripped at streamSimple boundary.\n\t\t\tconst authResult = await this._deps.modelRegistry.getApiKeyAndHeaders(model);\n\t\t\tconst apiKey = authResult.ok ? authResult.apiKey : undefined;\n\n\t\t\tconst pathEntries = this._deps.sessionManager.getBranch();\n\t\t\tconst settings = this._deps.settingsManager.getCompactionSettings();\n\n\t\t\tconst preparation = prepareCompaction(pathEntries, settings);\n\t\t\tif (!preparation) {\n\t\t\t\tconst lastEntry = pathEntries[pathEntries.length - 1];\n\t\t\t\tif (lastEntry?.type === \"compaction\") {\n\t\t\t\t\tthrow new Error(\"Already compacted\");\n\t\t\t\t}\n\t\t\t\tthrow new Error(\"Nothing to compact (session too small)\");\n\t\t\t}\n\n\t\t\tlet extensionCompaction: CompactionResult | undefined;\n\t\t\tlet fromExtension = false;\n\t\t\tconst extensionRunner = this._deps.getExtensionRunner();\n\n\t\t\tif (extensionRunner?.hasHandlers(\"session_before_compact\")) {\n\t\t\t\tconst result = (await extensionRunner.emit({\n\t\t\t\t\ttype: \"session_before_compact\",\n\t\t\t\t\tpreparation,\n\t\t\t\t\tbranchEntries: pathEntries,\n\t\t\t\t\tcustomInstructions,\n\t\t\t\t\tsignal: this._compactionAbortController.signal,\n\t\t\t\t})) as SessionBeforeCompactResult | undefined;\n\n\t\t\t\tif (result?.cancel) {\n\t\t\t\t\tthrow new Error(\"Compaction cancelled\");\n\t\t\t\t}\n\n\t\t\t\tif (result?.compaction) {\n\t\t\t\t\textensionCompaction = result.compaction;\n\t\t\t\t\tfromExtension = true;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tlet summary: string;\n\t\t\tlet firstKeptEntryId: string;\n\t\t\tlet tokensBefore: number;\n\t\t\tlet details: unknown;\n\n\t\t\tif (extensionCompaction) {\n\t\t\t\tsummary = extensionCompaction.summary;\n\t\t\t\tfirstKeptEntryId = extensionCompaction.firstKeptEntryId;\n\t\t\t\ttokensBefore = extensionCompaction.tokensBefore;\n\t\t\t\tdetails = extensionCompaction.details;\n\t\t\t} else {\n\t\t\t\tconst result = await compact(\n\t\t\t\t\tpreparation,\n\t\t\t\t\tmodel,\n\t\t\t\t\tapiKey,\n\t\t\t\t\tcustomInstructions,\n\t\t\t\t\tthis._compactionAbortController.signal,\n\t\t\t\t);\n\t\t\t\tsummary = result.summary;\n\t\t\t\tfirstKeptEntryId = result.firstKeptEntryId;\n\t\t\t\ttokensBefore = result.tokensBefore;\n\t\t\t\tdetails = result.details;\n\t\t\t}\n\n\t\t\tif (this._compactionAbortController.signal.aborted) {\n\t\t\t\tthrow new Error(\"Compaction cancelled\");\n\t\t\t}\n\n\t\t\tthis._deps.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);\n\t\t\tconst newEntries = this._deps.sessionManager.getEntries();\n\t\t\tconst sessionContext = this._deps.sessionManager.buildSessionContext();\n\t\t\tthis._deps.agent.state.messages = sessionContext.messages;\n\n\t\t\tconst savedCompactionEntry = newEntries.find(\n\t\t\t\t(e) => e.type === \"compaction\" && e.summary === summary,\n\t\t\t) as CompactionEntry | undefined;\n\n\t\t\tif (extensionRunner && savedCompactionEntry) {\n\t\t\t\tawait extensionRunner.emit({\n\t\t\t\t\ttype: \"session_compact\",\n\t\t\t\t\tcompactionEntry: savedCompactionEntry,\n\t\t\t\t\tfromExtension,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\treturn { summary, firstKeptEntryId, tokensBefore, details };\n\t\t} finally {\n\t\t\tthis._compactionAbortController = undefined;\n\t\t\tthis._deps.reconnectToAgent();\n\t\t}\n\t}\n\n\t/** Cancel in-progress compaction (manual or auto) */\n\tabortCompaction(): void {\n\t\tthis._compactionAbortController?.abort();\n\t\tthis._autoCompactionAbortController?.abort();\n\t}\n\n\t/** Cancel in-progress branch summarization */\n\tabortBranchSummary(): void {\n\t\tthis._branchSummaryAbortController?.abort();\n\t}\n\n\t/**\n\t * Check if compaction is needed and run it.\n\t * Called after agent_end and before prompt submission.\n\t *\n\t * Two cases:\n\t * 1. Overflow: LLM returned context overflow error, remove error message, compact, auto-retry\n\t * 2. Threshold: Context over threshold, compact, NO auto-retry\n\t *\n\t * @param assistantMessage The assistant message to check\n\t * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true\n\t */\n\tasync checkCompaction(assistantMessage: AssistantMessage, skipAbortedCheck = true): Promise<void> {\n\t\tconst settings = this._deps.settingsManager.getCompactionSettings();\n\t\tif (!settings.enabled) return;\n\n\t\tif (skipAbortedCheck && assistantMessage.stopReason === \"aborted\") return;\n\n\t\tconst model = this._deps.getModel();\n\t\tconst contextWindow = model?.contextWindow ?? 0;\n\n\t\tconst sameModel =\n\t\t\tmodel && assistantMessage.provider === model.provider && assistantMessage.model === model.id;\n\n\t\tconst branchEntries = this._deps.sessionManager.getBranch();\n\t\tconst compactionEntry = getLatestCompactionEntry(branchEntries);\n\t\tconst assistantIsFromBeforeCompaction =\n\t\t\tcompactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();\n\t\tif (assistantIsFromBeforeCompaction) return;\n\n\t\t// Case 1: Overflow - LLM returned context overflow error\n\t\tif (sameModel && isContextOverflow(assistantMessage, contextWindow)) {\n\t\t\tif (this._overflowRecoveryAttempted) {\n\t\t\t\tthis._deps.emit({\n\t\t\t\t\ttype: \"auto_compaction_end\",\n\t\t\t\t\tresult: undefined,\n\t\t\t\t\taborted: false,\n\t\t\t\t\twillRetry: false,\n\t\t\t\t\terrorMessage:\n\t\t\t\t\t\t\"Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.\",\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tthis._overflowRecoveryAttempted = true;\n\t\t\tconst messages = this._deps.agent.state.messages;\n\t\t\tif (messages.length > 0 && messages[messages.length - 1].role === \"assistant\") {\n\t\t\t\tthis._deps.agent.state.messages = messages.slice(0, -1);\n\t\t\t}\n\t\t\tawait this._runAutoCompaction(\"overflow\", true);\n\t\t\treturn;\n\t\t}\n\n\t\t// Case 2: Threshold - context is getting large\n\t\tlet contextTokens: number;\n\t\tif (assistantMessage.stopReason === \"error\") {\n\t\t\tconst messages = this._deps.agent.state.messages;\n\t\t\tconst estimate = estimateContextTokens(messages);\n\t\t\tif (estimate.lastUsageIndex === null) return;\n\t\t\tconst usageMsg = messages[estimate.lastUsageIndex];\n\t\t\tif (\n\t\t\t\tcompactionEntry &&\n\t\t\t\tusageMsg.role === \"assistant\" &&\n\t\t\t\t(usageMsg as AssistantMessage).timestamp <= new Date(compactionEntry.timestamp).getTime()\n\t\t\t) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tcontextTokens = estimate.tokens;\n\t\t} else {\n\t\t\tcontextTokens = calculateContextTokens(assistantMessage.usage);\n\t\t}\n\t\tif (shouldCompact(contextTokens, contextWindow, settings)) {\n\t\t\tawait this._runAutoCompaction(\"threshold\", false);\n\t\t}\n\t}\n\n\t/** Toggle auto-compaction setting */\n\tsetAutoCompactionEnabled(enabled: boolean): void {\n\t\tthis._deps.settingsManager.setCompactionEnabled(enabled);\n\t}\n\n\t/** Whether auto-compaction is enabled */\n\tget autoCompactionEnabled(): boolean {\n\t\treturn this._deps.settingsManager.getCompactionEnabled();\n\t}\n\n\t// =========================================================================\n\t// Private helpers\n\t// =========================================================================\n\n\tprivate async _runAutoCompaction(reason: \"overflow\" | \"threshold\", willRetry: boolean): Promise<void> {\n\t\tconst settings = this._deps.settingsManager.getCompactionSettings();\n\n\t\tthis._deps.emit({ type: \"auto_compaction_start\", reason });\n\t\tthis._autoCompactionAbortController = new AbortController();\n\n\t\ttry {\n\t\t\tconst model = this._deps.getModel();\n\t\t\tif (!model) {\n\t\t\t\tthis._deps.emit({ type: \"auto_compaction_end\", result: undefined, aborted: false, willRetry: false });\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (!this._deps.modelRegistry.isProviderRequestReady(model.provider)) {\n\t\t\t\tthis._deps.emit({ type: \"auto_compaction_end\", result: undefined, aborted: false, willRetry: false });\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t// undefined for providers without API keys (e.g. external CLI) — stripped at streamSimple boundary.\n\t\t\tconst authResult = await this._deps.modelRegistry.getApiKeyAndHeaders(model);\n\t\t\tconst apiKey = authResult.ok ? authResult.apiKey : undefined;\n\n\t\t\tconst pathEntries = this._deps.sessionManager.getBranch();\n\t\t\tconst preparation = prepareCompaction(pathEntries, settings);\n\t\t\tif (!preparation) {\n\t\t\t\tthis._deps.emit({ type: \"auto_compaction_end\", result: undefined, aborted: false, willRetry: false });\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlet extensionCompaction: CompactionResult | undefined;\n\t\t\tlet fromExtension = false;\n\t\t\tconst extensionRunner = this._deps.getExtensionRunner();\n\n\t\t\tif (extensionRunner?.hasHandlers(\"session_before_compact\")) {\n\t\t\t\tconst extensionResult = (await extensionRunner.emit({\n\t\t\t\t\ttype: \"session_before_compact\",\n\t\t\t\t\tpreparation,\n\t\t\t\t\tbranchEntries: pathEntries,\n\t\t\t\t\tcustomInstructions: undefined,\n\t\t\t\t\tsignal: this._autoCompactionAbortController.signal,\n\t\t\t\t})) as SessionBeforeCompactResult | undefined;\n\n\t\t\t\tif (extensionResult?.cancel) {\n\t\t\t\t\tthis._deps.emit({\n\t\t\t\t\t\ttype: \"auto_compaction_end\",\n\t\t\t\t\t\tresult: undefined,\n\t\t\t\t\t\taborted: true,\n\t\t\t\t\t\twillRetry: false,\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tif (extensionResult?.compaction) {\n\t\t\t\t\textensionCompaction = extensionResult.compaction;\n\t\t\t\t\tfromExtension = true;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tlet summary: string;\n\t\t\tlet firstKeptEntryId: string;\n\t\t\tlet tokensBefore: number;\n\t\t\tlet details: unknown;\n\n\t\t\tif (extensionCompaction) {\n\t\t\t\tsummary = extensionCompaction.summary;\n\t\t\t\tfirstKeptEntryId = extensionCompaction.firstKeptEntryId;\n\t\t\t\ttokensBefore = extensionCompaction.tokensBefore;\n\t\t\t\tdetails = extensionCompaction.details;\n\t\t\t} else {\n\t\t\t\tconst compactResult = await compact(\n\t\t\t\t\tpreparation,\n\t\t\t\t\tmodel,\n\t\t\t\t\tapiKey,\n\t\t\t\t\tundefined,\n\t\t\t\t\tthis._autoCompactionAbortController.signal,\n\t\t\t\t);\n\t\t\t\tsummary = compactResult.summary;\n\t\t\t\tfirstKeptEntryId = compactResult.firstKeptEntryId;\n\t\t\t\ttokensBefore = compactResult.tokensBefore;\n\t\t\t\tdetails = compactResult.details;\n\t\t\t}\n\n\t\t\tif (this._autoCompactionAbortController.signal.aborted) {\n\t\t\t\tthis._deps.emit({ type: \"auto_compaction_end\", result: undefined, aborted: true, willRetry: false });\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tthis._deps.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);\n\t\t\tconst newEntries = this._deps.sessionManager.getEntries();\n\t\t\tconst sessionContext = this._deps.sessionManager.buildSessionContext();\n\t\t\tthis._deps.agent.state.messages = sessionContext.messages;\n\n\t\t\tconst savedCompactionEntry = newEntries.find(\n\t\t\t\t(e) => e.type === \"compaction\" && e.summary === summary,\n\t\t\t) as CompactionEntry | undefined;\n\n\t\t\tif (extensionRunner && savedCompactionEntry) {\n\t\t\t\tawait extensionRunner.emit({\n\t\t\t\t\ttype: \"session_compact\",\n\t\t\t\t\tcompactionEntry: savedCompactionEntry,\n\t\t\t\t\tfromExtension,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst result: CompactionResult = { summary, firstKeptEntryId, tokensBefore, details };\n\t\t\tthis._deps.emit({ type: \"auto_compaction_end\", result, aborted: false, willRetry });\n\n\t\t\tif (willRetry) {\n\t\t\t\tconst messages = this._deps.agent.state.messages;\n\t\t\t\tconst lastMsg = messages[messages.length - 1];\n\t\t\t\tif (lastMsg?.role === \"assistant\" && (lastMsg as AssistantMessage).stopReason === \"error\") {\n\t\t\t\t\tthis._deps.agent.state.messages = messages.slice(0, -1);\n\t\t\t\t}\n\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tthis._deps.agent.continue().catch(() => {});\n\t\t\t\t}, 100);\n\t\t\t} else if (this._deps.agent.hasQueuedMessages()) {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tthis._deps.agent.continue().catch(() => {});\n\t\t\t\t}, 100);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tconst errorMessage = getErrorMessage(error);\n\t\t\tthis._deps.emit({\n\t\t\t\ttype: \"auto_compaction_end\",\n\t\t\t\tresult: undefined,\n\t\t\t\taborted: false,\n\t\t\t\twillRetry: false,\n\t\t\t\terrorMessage:\n\t\t\t\t\treason === \"overflow\"\n\t\t\t\t\t\t? `Context overflow recovery failed: ${errorMessage}`\n\t\t\t\t\t\t: `Auto-compaction failed: ${errorMessage}`,\n\t\t\t});\n\t\t} finally {\n\t\t\tthis._autoCompactionAbortController = undefined;\n\t\t}\n\t}\n}\n"]}

package/packages/gsd-agent-core/dist/contextual-tips.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Contextual tips system — shows non-intrusive, session-scoped hints
+ * when user behavior suggests they'd benefit from knowing a feature.
+ *
+ * Each tip fires at most `maxShows` times per session. Tips are
+ * evaluated in order; the first match wins per input event.
+ */
+export interface TipContext {
+    /** The raw input text the user submitted */
+    input: string;
+    /** Whether the agent is currently streaming */
+    isStreaming: boolean;
+    /** Current thinking level (e.g. "off", "low", "high", "xhigh") */
+    thinkingLevel?: string;
+    /** Number of `!` (included) bash commands run this session */
+    bashIncludedCount: number;
+    /** Approximate context usage percentage (0–100), if known */
+    contextPercent?: number;
+}
+export interface Tip {
+    id: string;
+    /** Maximum times this tip is shown per session */
+    maxShows: number;
+    /** Returns the tip message if the tip should fire, or null to skip */
+    evaluate: (ctx: TipContext) => string | null;
+}
+export declare class ContextualTips {
+    /** Map of tip ID → number of times shown this session */
+    private showCounts;
+    /** Track ! bash commands for double-bang reminder */
+    private _bashIncludedCount;
+    /** Increment the bash-included counter. Call when user runs ! (not !!) command. */
+    recordBashIncluded(): void;
+    get bashIncludedCount(): number;
+    /**
+     * Evaluate all tips against the current input context.
+     * Returns the first matching tip message, or null if none apply.
+     */
+    evaluate(ctx: Omit<TipContext, "bashIncludedCount">): string | null;
+    /** Reset all counters (e.g. on new session). */
+    reset(): void;
+}
+//# sourceMappingURL=contextual-tips.d.ts.map

package/packages/gsd-agent-core/dist/contextual-tips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextual-tips.d.ts","sourceRoot":"","sources":["../src/contextual-tips.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,UAAU;IAC1B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,WAAW,EAAE,OAAO,CAAC;IACrB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,QAAQ,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,IAAI,CAAC;CAC7C;AA8JD,qBAAa,cAAc;IAC1B,yDAAyD;IACzD,OAAO,CAAC,UAAU,CAA6B;IAC/C,qDAAqD;IACrD,OAAO,CAAC,kBAAkB,CAAK;IAE/B,mFAAmF;IACnF,kBAAkB,IAAI,IAAI;IAI1B,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,GAAG,MAAM,GAAG,IAAI;IAoBnE,gDAAgD;IAChD,KAAK,IAAI,IAAI;CAIb"}

package/packages/gsd-agent-core/dist/contextual-tips.js

@@ -0,0 +1,208 @@
+/**
+ * Contextual tips system — shows non-intrusive, session-scoped hints
+ * when user behavior suggests they'd benefit from knowing a feature.
+ *
+ * Each tip fires at most `maxShows` times per session. Tips are
+ * evaluated in order; the first match wins per input event.
+ */
+// Shell commands that obviously run locally and don't need the LLM.
+// Intentionally conservative — these are unambiguous filesystem/info commands.
+const LOCAL_SHELL_COMMANDS = new Set([
+    "ls",
+    "ll",
+    "la",
+    "pwd",
+    "cd",
+    "dir",
+    "cat",
+    "head",
+    "tail",
+    "wc",
+    "file",
+    "which",
+    "whoami",
+    "echo",
+    "date",
+    "tree",
+    "find",
+    "grep",
+    "rg",
+    "clear",
+    "env",
+    "df",
+    "du",
+    "uname",
+    "hostname",
+    "mkdir",
+    "rm",
+    "cp",
+    "mv",
+    "touch",
+    "chmod",
+    "less",
+    "more",
+    "sort",
+    "uniq",
+    "sed",
+    "awk",
+    "curl",
+    "wget",
+    "tar",
+    "zip",
+    "unzip",
+    "git",
+    "docker",
+    "npm",
+    "npx",
+    "yarn",
+    "pnpm",
+    "node",
+    "python",
+    "python3",
+    "pip",
+    "pip3",
+    "make",
+    "cargo",
+    "go",
+    "ruby",
+    "brew",
+]);
+/**
+ * Extract the first token from input, ignoring leading whitespace.
+ * Returns lowercase for case-insensitive matching.
+ */
+function firstToken(input) {
+    const trimmed = input.trimStart();
+    const spaceIdx = trimmed.search(/\s/);
+    const token = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+    return token.toLowerCase();
+}
+/**
+ * Check if input looks like a bare shell command (no !, //, or slash prefix).
+ */
+function looksLikeShellCommand(input) {
+    const trimmed = input.trimStart();
+    // Already prefixed — user knows what they're doing
+    if (trimmed.startsWith("!") || trimmed.startsWith("/"))
+        return false;
+    // Multi-line or very long inputs are probably prompts
+    if (trimmed.includes("\n") || trimmed.length > 120)
+        return false;
+    return LOCAL_SHELL_COMMANDS.has(firstToken(trimmed));
+}
+const TIPS = [
+    // 1. Shell command reminder
+    {
+        id: "shell-command-prefix",
+        maxShows: 2,
+        evaluate(ctx) {
+            if (!looksLikeShellCommand(ctx.input))
+                return null;
+            const cmd = firstToken(ctx.input);
+            return `Tip: "${cmd}" looks like a shell command. Prefix with ! to run locally, or !! to run without using tokens.`;
+        },
+    },
+    // 2. Large paste warning
+    {
+        id: "large-paste",
+        maxShows: 2,
+        evaluate(ctx) {
+            if (ctx.input.length < 2000)
+                return null;
+            // Slash commands and bash prefixes are intentional
+            if (ctx.input.trimStart().startsWith("/") || ctx.input.trimStart().startsWith("!"))
+                return null;
+            return "Tip: Large inputs consume many tokens. Consider saving to a file and asking the agent to read it.";
+        },
+    },
+    // 3. Thinking level awareness
+    {
+        id: "thinking-level-high",
+        maxShows: 1,
+        evaluate(ctx) {
+            const level = ctx.thinkingLevel?.toLowerCase();
+            if (level !== "high" && level !== "xhigh")
+                return null;
+            // Only fire for short, simple-looking inputs (likely simple questions)
+            const trimmed = ctx.input.trim();
+            if (trimmed.length > 80 || trimmed.includes("\n"))
+                return null;
+            // Don't fire on slash or bash commands
+            if (trimmed.startsWith("/") || trimmed.startsWith("!"))
+                return null;
+            return `Tip: Thinking is set to ${level}. Use Ctrl+T to lower it for simple questions — saves tokens.`;
+        },
+    },
+    // 4. Double-bang reminder
+    {
+        id: "double-bang-reminder",
+        maxShows: 2,
+        evaluate(ctx) {
+            // Fire after user has run 3+ included (!) bash commands
+            if (ctx.bashIncludedCount < 3)
+                return null;
+            // Only trigger on a ! command (not !!)
+            const trimmed = ctx.input.trimStart();
+            if (!trimmed.startsWith("!") || trimmed.startsWith("!!"))
+                return null;
+            return "Tip: Use !! instead of ! to keep command output out of agent context and save tokens.";
+        },
+    },
+    // 5. Compaction nudge
+    {
+        id: "compaction-nudge",
+        maxShows: 1,
+        evaluate(ctx) {
+            if (ctx.contextPercent === undefined || ctx.contextPercent < 70)
+                return null;
+            // Don't nag on slash/bash
+            const trimmed = ctx.input.trimStart();
+            if (trimmed.startsWith("/") || trimmed.startsWith("!"))
+                return null;
+            return "Tip: Context is getting full. Use /compact to summarize the conversation and free up space.";
+        },
+    },
+];
+// ─── Session-scoped tracker ──────────────────────────────────────────────────
+export class ContextualTips {
+    constructor() {
+        /** Map of tip ID → number of times shown this session */
+        this.showCounts = new Map();
+        /** Track ! bash commands for double-bang reminder */
+        this._bashIncludedCount = 0;
+    }
+    /** Increment the bash-included counter. Call when user runs ! (not !!) command. */
+    recordBashIncluded() {
+        this._bashIncludedCount++;
+    }
+    get bashIncludedCount() {
+        return this._bashIncludedCount;
+    }
+    /**
+     * Evaluate all tips against the current input context.
+     * Returns the first matching tip message, or null if none apply.
+     */
+    evaluate(ctx) {
+        const fullCtx = {
+            ...ctx,
+            bashIncludedCount: this._bashIncludedCount,
+        };
+        for (const tip of TIPS) {
+            const shown = this.showCounts.get(tip.id) ?? 0;
+            if (shown >= tip.maxShows)
+                continue;
+            const message = tip.evaluate(fullCtx);
+            if (message) {
+                this.showCounts.set(tip.id, shown + 1);
+                return message;
+            }
+        }
+        return null;
+    }
+    /** Reset all counters (e.g. on new session). */
+    reset() {
+        this.showCounts.clear();
+        this._bashIncludedCount = 0;
+    }
+}
+//# sourceMappingURL=contextual-tips.js.map