gsd-pi 2.76.0 → 2.77.0-dev.538325aea

package/packages/gsd-agent-core/src/compaction-orchestrator.ts

@@ -0,0 +1,449 @@
+/**
+ * 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 type { Agent } from "@gsd/pi-agent-core";
+import type { Api, AssistantMessage, Model } from "@gsd/pi-ai";
+import { isContextOverflow } from "@gsd/pi-ai";
+import {
+	type CompactionResult,
+	calculateContextTokens,
+	compact,
+	estimateContextTokens,
+	prepareCompaction,
+	shouldCompact,
+} from "./compaction/index.js";
+import type { ExtensionRunner } from "@gsd/agent-types";
+import type { ModelRegistry } from "@gsd/agent-types";
+import { getLatestCompactionEntry } from "@gsd/pi-coding-agent";
+import type { CompactionEntry, SessionManager } from "@gsd/agent-types";
+import type { SettingsManager } from "@gsd/agent-types";
+import type { AgentSessionEvent } from "./agent-session.js";
+
+// Local shims for types/functions absent from @gsd/pi-coding-agent 0.67.2 public API.
+// Phase 09 moves these to @gsd/agent-types or resolves via upstream PR.
+
+/** Result returned by session_before_compact extension handlers. */
+interface SessionBeforeCompactResult {
+	cancel?: boolean;
+	compaction?: CompactionResult;
+}
+
+/** Extract a human-readable error message from an unknown thrown value. */
+function getErrorMessage(e: unknown): string {
+	return e instanceof Error ? e.message : String(e);
+}
+
+/** Extended ModelRegistry with GSD provider readiness check. */
+interface ModelRegistryWithReadiness extends ModelRegistry {
+	isProviderRequestReady(provider: string): boolean;
+	getApiKeyAndHeaders(model: import("@gsd/pi-ai").Model<import("@gsd/pi-ai").Api>): Promise<
+		{ ok: true; apiKey?: string; headers?: Record<string, string> } | { ok: false; error: string }
+	>;
+}
+
+/** Dependencies injected from AgentSession into CompactionOrchestrator */
+export interface CompactionOrchestratorDeps {
+	readonly agent: Agent;
+	readonly sessionManager: SessionManager;
+	readonly settingsManager: SettingsManager;
+	readonly modelRegistry: ModelRegistryWithReadiness;
+	getModel: () => Model<Api> | undefined;
+	getSessionId: () => string;
+	getExtensionRunner: () => ExtensionRunner | undefined;
+	emit: (event: AgentSessionEvent) => void;
+	disconnectFromAgent: () => void;
+	reconnectToAgent: () => void;
+	abort: () => Promise<void>;
+}
+
+export class CompactionOrchestrator {
+	private _compactionAbortController: AbortController | undefined = undefined;
+	private _autoCompactionAbortController: AbortController | undefined = undefined;
+	private _overflowRecoveryAttempted = false;
+	private _branchSummaryAbortController: AbortController | undefined = undefined;
+
+	constructor(private readonly _deps: CompactionOrchestratorDeps) {}
+
+	/** Whether compaction or branch summarization is currently running */
+	get isCompacting(): boolean {
+		return (
+			this._autoCompactionAbortController !== undefined ||
+			this._compactionAbortController !== undefined ||
+			this._branchSummaryAbortController !== undefined
+		);
+	}
+
+	/** Reset overflow recovery flag (called when a new user message starts) */
+	resetOverflowRecovery(): void {
+		this._overflowRecoveryAttempted = false;
+	}
+
+	/** Mark overflow recovery as not needed (called on successful assistant response) */
+	clearOverflowRecovery(): void {
+		this._overflowRecoveryAttempted = false;
+	}
+
+	/** Get/set the branch summary abort controller (used by navigateTree) */
+	get branchSummaryAbortController(): AbortController | undefined {
+		return this._branchSummaryAbortController;
+	}
+	set branchSummaryAbortController(controller: AbortController | undefined) {
+		this._branchSummaryAbortController = controller;
+	}
+
+	/**
+	 * Manually compact the session context.
+	 * Aborts current agent operation first.
+	 * @param customInstructions Optional instructions for the compaction summary
+	 */
+	async compact(customInstructions?: string): Promise<CompactionResult> {
+		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: CompactionResult | undefined;
+			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,
+				})) as SessionBeforeCompactResult | undefined;
+
+				if (result?.cancel) {
+					throw new Error("Compaction cancelled");
+				}
+
+				if (result?.compaction) {
+					extensionCompaction = result.compaction;
+					fromExtension = true;
+				}
+			}
+
+			let summary: string;
+			let firstKeptEntryId: string;
+			let tokensBefore: number;
+			let details: unknown;
+
+			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,
+			) as CompactionEntry | undefined;
+
+			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(): void {
+		this._compactionAbortController?.abort();
+		this._autoCompactionAbortController?.abort();
+	}
+
+	/** Cancel in-progress branch summarization */
+	abortBranchSummary(): void {
+		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: AssistantMessage, skipAbortedCheck = true): Promise<void> {
+		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: number;
+		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 as AssistantMessage).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: boolean): void {
+		this._deps.settingsManager.setCompactionEnabled(enabled);
+	}
+
+	/** Whether auto-compaction is enabled */
+	get autoCompactionEnabled(): boolean {
+		return this._deps.settingsManager.getCompactionEnabled();
+	}
+
+	// =========================================================================
+	// Private helpers
+	// =========================================================================
+
+	private async _runAutoCompaction(reason: "overflow" | "threshold", willRetry: boolean): Promise<void> {
+		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: CompactionResult | undefined;
+			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,
+				})) as SessionBeforeCompactResult | undefined;
+
+				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: string;
+			let firstKeptEntryId: string;
+			let tokensBefore: number;
+			let details: unknown;
+
+			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,
+			) as CompactionEntry | undefined;
+
+			if (extensionRunner && savedCompactionEntry) {
+				await extensionRunner.emit({
+					type: "session_compact",
+					compactionEntry: savedCompactionEntry,
+					fromExtension,
+				});
+			}
+
+			const result: CompactionResult = { 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 as AssistantMessage).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;
+		}
+	}
+}

package/packages/gsd-agent-core/src/contextual-tips.ts

@@ -0,0 +1,232 @@
+/**
+ * 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.
+ */
+
+// ─── Tip definitions ─────────────────────────────────────────────────────────
+
+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;
+}
+
+// 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: string): string {
+	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: string): boolean {
+	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: Tip[] = [
+	// 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 {
+	/** Map of tip ID → number of times shown this session */
+	private showCounts = new Map<string, number>();
+	/** Track ! bash commands for double-bang reminder */
+	private _bashIncludedCount = 0;
+
+	/** Increment the bash-included counter. Call when user runs ! (not !!) command. */
+	recordBashIncluded(): void {
+		this._bashIncludedCount++;
+	}
+
+	get bashIncludedCount(): number {
+		return this._bashIncludedCount;
+	}
+
+	/**
+	 * 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 {
+		const fullCtx: TipContext = {
+			...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(): void {
+		this.showCounts.clear();
+		this._bashIncludedCount = 0;
+	}
+}