gsd-pi 2.77.0-dev.538325aea → 2.77.0

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

@@ -1,449 +0,0 @@
-/**
- * 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

@@ -1,232 +0,0 @@
-/**
- * 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;
-	}
-}