@oh-my-pi/pi-coding-agent 5.5.0 → 5.6.7

package/src/core/agent-session.ts

@@ -25,6 +25,7 @@ import {
 	calculateContextTokens,
 	collectEntriesForBranchSummary,
 	compact,
+	estimateTokens,
 	generateBranchSummary,
 	prepareCompaction,
 	shouldCompact,
@@ -43,6 +44,7 @@ import type {
 	TurnEndEvent,
 	TurnStartEvent,
 } from "./extensions";
+import type { CompactOptions, ContextUsage } from "./extensions/types";
 import { extractFileMentions, generateFileMentionMessages } from "./file-mentions";
 import type { HookCommandContext } from "./hooks/types";
 import { logger } from "./logger";
@@ -65,7 +67,13 @@ import type { TtsrManager } from "./ttsr";
 export type AgentSessionEvent =
 	| AgentEvent
 	| { type: "auto_compaction_start"; reason: "threshold" | "overflow" }
-	| { type: "auto_compaction_end"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean }
+	| {
+			type: "auto_compaction_end";
+			result: CompactionResult | undefined;
+			aborted: boolean;
+			willRetry: boolean;
+			errorMessage?: string;
+	  }
 	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
 	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
 	| { type: "ttsr_triggered"; rules: Rule[] }
@@ -906,6 +914,7 @@ export class AgentSession {
 				process.exit(0);
 			},
 			hasQueuedMessages: () => this.queuedMessageCount > 0,
+			getContextUsage: () => this.getContextUsage(),
 			waitForIdle: () => this.agent.waitForIdle(),
 			newSession: async (options) => {
 				const success = await this.newSession({ parentSession: options?.parentSession });
@@ -925,6 +934,12 @@ export class AgentSession {
 				const result = await this.navigateTree(targetId, { summarize: options?.summarize });
 				return { cancelled: result.cancelled };
 			},
+			compact: async (instructionsOrOptions) => {
+				const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
+				const options =
+					instructionsOrOptions && typeof instructionsOrOptions === "object" ? instructionsOrOptions : undefined;
+				await this.compact(instructions, options);
+			},
 		};
 	}
 
@@ -967,7 +982,7 @@ export class AgentSession {
 				});
 			} else {
 				const message = err instanceof Error ? err.message : String(err);
-				console.error(`Custom command "${commandName}" failed: ${message}`);
+				logger.error("Custom command failed", { commandName, error: message });
 			}
 			return ""; // Command was handled (with error)
 		}
@@ -1533,8 +1548,9 @@ export class AgentSession {
 	 * Manually compact the session context.
 	 * Aborts current agent operation first.
 	 * @param customInstructions Optional instructions for the compaction summary
+	 * @param options Optional callbacks for completion/error handling
 	 */
-	async compact(customInstructions?: string): Promise<CompactionResult> {
+	async compact(customInstructions?: string, options?: CompactOptions): Promise<CompactionResult> {
 		this._disconnectFromAgent();
 		await this.abort();
 		this._compactionAbortController = new AbortController();
@@ -1632,12 +1648,18 @@ export class AgentSession {
 				});
 			}
 
-			return {
+			const compactionResult: CompactionResult = {
 				summary,
 				firstKeptEntryId,
 				tokensBefore,
 				details,
 			};
+			options?.onComplete?.(compactionResult);
+			return compactionResult;
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			options?.onError?.(err);
+			throw error;
 		} finally {
 			this._compactionAbortController = undefined;
 			this._reconnectToAgent();
@@ -2046,15 +2068,17 @@ export class AgentSession {
 				}, 100);
 			}
 		} catch (error) {
-			this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
-
-			if (reason === "overflow") {
-				throw new Error(
-					`Context overflow: ${
-						error instanceof Error ? error.message : "compaction failed"
-					}. Your input may be too large for the context window.`,
-				);
-			}
+			const errorMessage = error instanceof Error ? error.message : "compaction failed";
+			this._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;
 		}
@@ -2092,8 +2116,8 @@ export class AgentSession {
 	}
 
 	private _isRetryableErrorMessage(errorMessage: string): boolean {
-		// Match: overloaded_error, rate limit, usage limit, 429, 500, 502, 503, 504, service unavailable, connection error
-		return /overloaded|rate.?limit|usage.?limit|too many requests|429|500|502|503|504|service.?unavailable|server error|internal error|connection.?error/i.test(
+		// Match: overloaded_error, rate limit, usage limit, 429, 500, 502, 503, 504, service unavailable, connection error, fetch failed
+		return /overloaded|rate.?limit|usage.?limit|too many requests|429|500|502|503|504|service.?unavailable|server error|internal error|connection.?error|fetch failed/i.test(
 			errorMessage,
 		);
 	}
@@ -2804,6 +2828,85 @@ export class AgentSession {
 		};
 	}
 
+	/**
+	 * Get current context usage statistics.
+	 * Uses the last assistant message's usage data when available,
+	 * otherwise estimates tokens for all messages.
+	 */
+	getContextUsage(): ContextUsage | undefined {
+		const model = this.model;
+		if (!model) return undefined;
+
+		const contextWindow = model.contextWindow ?? 0;
+		if (contextWindow <= 0) return undefined;
+
+		const estimate = this._estimateContextTokens();
+		const percent = (estimate.tokens / contextWindow) * 100;
+
+		return {
+			tokens: estimate.tokens,
+			contextWindow,
+			percent,
+			usageTokens: estimate.usageTokens,
+			trailingTokens: estimate.trailingTokens,
+			lastUsageIndex: estimate.lastUsageIndex,
+		};
+	}
+
+	/**
+	 * Estimate context tokens from messages, using the last assistant usage when available.
+	 */
+	private _estimateContextTokens(): {
+		tokens: number;
+		usageTokens: number;
+		trailingTokens: number;
+		lastUsageIndex: number | null;
+	} {
+		const messages = this.messages;
+
+		// Find last assistant message with usage
+		let lastUsageIndex: number | null = null;
+		let lastUsage: Usage | undefined;
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const msg = messages[i];
+			if (msg.role === "assistant") {
+				const assistantMsg = msg as AssistantMessage;
+				if (assistantMsg.usage) {
+					lastUsage = assistantMsg.usage;
+					lastUsageIndex = i;
+					break;
+				}
+			}
+		}
+
+		if (!lastUsage || lastUsageIndex === null) {
+			// No usage data - estimate all messages
+			let estimated = 0;
+			for (const message of messages) {
+				estimated += estimateTokens(message);
+			}
+			return {
+				tokens: estimated,
+				usageTokens: 0,
+				trailingTokens: estimated,
+				lastUsageIndex: null,
+			};
+		}
+
+		const usageTokens = calculateContextTokens(lastUsage);
+		let trailingTokens = 0;
+		for (let i = lastUsageIndex + 1; i < messages.length; i++) {
+			trailingTokens += estimateTokens(messages[i]);
+		}
+
+		return {
+			tokens: usageTokens + trailingTokens,
+			usageTokens,
+			trailingTokens,
+			lastUsageIndex,
+		};
+	}
+
 	/**
 	 * Export session to HTML.
 	 * @param outputPath Optional output path (defaults to session directory)

package/src/core/bash-executor.ts

@@ -6,16 +6,12 @@
  * - Direct calls from modes that need bash execution
  */
 
-import { createWriteStream, type WriteStream } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import type { Subprocess } from "bun";
-import { nanoid } from "nanoid";
-import stripAnsi from "strip-ansi";
-import { getShellConfig, killProcessTree, sanitizeBinaryOutput } from "../utils/shell";
+import { getShellConfig, killProcessTree } from "../utils/shell";
 import { getOrCreateSnapshot, getSnapshotSourceCommand } from "../utils/shell-snapshot";
+import { createOutputSink, pumpStream } from "./streaming-output";
 import type { BashOperations } from "./tools/bash";
-import { DEFAULT_MAX_BYTES, truncateTail } from "./tools/truncate";
+import { DEFAULT_MAX_BYTES } from "./tools/truncate";
 import { ScopeSignal } from "./utils";
 
 // ============================================================================
@@ -50,83 +46,6 @@ export interface BashResult {
 // Implementation
 // ============================================================================
 
-function createSanitizer(): TransformStream<Uint8Array, string> {
-	const decoder = new TextDecoder();
-	return new TransformStream({
-		transform(chunk, controller) {
-			const text = sanitizeBinaryOutput(stripAnsi(decoder.decode(chunk, { stream: true }))).replace(/\r/g, "");
-			controller.enqueue(text);
-		},
-	});
-}
-
-async function pumpStream(readable: ReadableStream<Uint8Array>, writer: WritableStreamDefaultWriter<string>) {
-	const reader = readable.pipeThrough(createSanitizer()).getReader();
-	try {
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			await writer.write(value);
-		}
-	} finally {
-		reader.releaseLock();
-	}
-}
-
-function createOutputSink(
-	spillThreshold: number,
-	maxBuffer: number,
-	onChunk?: (text: string) => void,
-): WritableStream<string> & {
-	dump: (annotation?: string) => { output: string; truncated: boolean; fullOutputPath?: string };
-} {
-	const chunks: string[] = [];
-	let chunkBytes = 0;
-	let totalBytes = 0;
-	let fullOutputPath: string | undefined;
-	let fullOutputStream: WriteStream | undefined;
-
-	const sink = new WritableStream<string>({
-		write(text) {
-			totalBytes += text.length;
-
-			// Spill to temp file if needed
-			if (totalBytes > spillThreshold && !fullOutputPath) {
-				fullOutputPath = join(tmpdir(), `omp-${nanoid()}.buffer`);
-				const ts = createWriteStream(fullOutputPath);
-				chunks.forEach((c) => {
-					ts.write(c);
-				});
-				fullOutputStream = ts;
-			}
-			fullOutputStream?.write(text);
-
-			// Rolling buffer
-			chunks.push(text);
-			chunkBytes += text.length;
-			while (chunkBytes > maxBuffer && chunks.length > 1) {
-				chunkBytes -= chunks.shift()!.length;
-			}
-
-			onChunk?.(text);
-		},
-		close() {
-			fullOutputStream?.end();
-		},
-	});
-
-	return Object.assign(sink, {
-		dump(annotation?: string) {
-			if (annotation) {
-				chunks.push(`\n\n${annotation}`);
-			}
-			const full = chunks.join("");
-			const { content, truncated } = truncateTail(full);
-			return { output: truncated ? content : full, truncated, fullOutputPath: fullOutputPath };
-		},
-	});
-}
-
 /**
  * Execute a bash command with optional streaming and cancellation support.
  *

package/src/core/compaction/compaction.ts

@@ -7,7 +7,7 @@
 
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, Model, Usage } from "@oh-my-pi/pi-ai";
-import { complete, completeSimple } from "@oh-my-pi/pi-ai";
+import { completeSimple } from "@oh-my-pi/pi-ai";
 import compactionSummaryPrompt from "../../prompts/compaction/compaction-summary.md" with { type: "text" };
 import compactionTurnPrefixPrompt from "../../prompts/compaction/compaction-turn-prefix.md" with { type: "text" };
 import compactionUpdateSummaryPrompt from "../../prompts/compaction/compaction-update-summary.md" with { type: "text" };
@@ -642,17 +642,22 @@ async function generateTurnPrefixSummary(
 ): Promise<string> {
 	const maxTokens = Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix
 
-	const transformedMessages = convertToLlm(messages);
+	const llmMessages = convertToLlm(messages);
+	const conversationText = serializeConversation(llmMessages);
+	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
 	const summarizationMessages = [
-		...transformedMessages,
 		{
 			role: "user" as const,
-			content: [{ type: "text" as const, text: TURN_PREFIX_SUMMARIZATION_PROMPT }],
+			content: [{ type: "text" as const, text: promptText }],
 			timestamp: Date.now(),
 		},
 	];
 
-	const response = await complete(model, { messages: summarizationMessages }, { maxTokens, signal, apiKey });
+	const response = await completeSimple(
+		model,
+		{ systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages },
+		{ maxTokens, signal, apiKey, reasoning: "high" },
+	);
 
 	if (response.stopReason === "error") {
 		throw new Error(`Turn prefix summarization failed: ${response.errorMessage || "Unknown error"}`);

package/src/core/extensions/index.ts

@@ -54,6 +54,8 @@ export type {
 	GetAllToolsHandler,
 	GetThinkingLevelHandler,
 	GrepToolResultEvent,
+	InputEvent,
+	InputEventResult,
 	KeybindingsManager,
 	LoadExtensionsResult,
 	LsToolResultEvent,

package/src/core/extensions/loader.ts

@@ -49,6 +49,7 @@ export function createExtensionRuntime(): ExtensionRuntime {
 		sendMessage: notInitialized,
 		sendUserMessage: notInitialized,
 		appendEntry: notInitialized,
+		setLabel: notInitialized,
 		getActiveTools: notInitialized,
 		getAllTools: notInitialized,
 		setActiveTools: notInitialized,
@@ -88,10 +89,21 @@ function createExtensionAPI(
 			});
 		},
 
-		registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void {
+		registerCommand(
+			name: string,
+			options: {
+				description?: string;
+				getArgumentCompletions?: RegisteredCommand["getArgumentCompletions"];
+				handler: RegisteredCommand["handler"];
+			},
+		): void {
 			extension.commands.set(name, { name, ...options });
 		},
 
+		setLabel(label: string): void {
+			extension.label = label;
+		},
+
 		registerShortcut(
 			shortcut: KeyId,
 			options: {

package/src/core/extensions/runner.ts

@@ -12,8 +12,10 @@ import type { SessionManager } from "../session-manager";
 import type {
 	BeforeAgentStartEvent,
 	BeforeAgentStartEventResult,
+	CompactOptions,
 	ContextEvent,
 	ContextEventResult,
+	ContextUsage,
 	Extension,
 	ExtensionActions,
 	ExtensionCommandContext,
@@ -26,6 +28,8 @@ import type {
 	ExtensionRuntime,
 	ExtensionShortcut,
 	ExtensionUIContext,
+	InputEvent,
+	InputEventResult,
 	MessageRenderer,
 	RegisteredCommand,
 	RegisteredTool,
@@ -110,6 +114,8 @@ export class ExtensionRunner {
 	private waitForIdleFn: () => Promise<void> = async () => {};
 	private abortFn: () => void = () => {};
 	private hasPendingMessagesFn: () => boolean = () => false;
+	private getContextUsageFn: () => ContextUsage | undefined = () => undefined;
+	private compactFn: (instructionsOrOptions?: string | CompactOptions) => Promise<void> = async () => {};
 	private newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
 	private branchHandler: BranchHandler = async () => ({ cancelled: false });
 	private navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
@@ -160,6 +166,8 @@ export class ExtensionRunner {
 			this.newSessionHandler = commandContextActions.newSession;
 			this.branchHandler = commandContextActions.branch;
 			this.navigateTreeHandler = commandContextActions.navigateTree;
+			this.getContextUsageFn = commandContextActions.getContextUsage;
+			this.compactFn = commandContextActions.compact;
 		}
 
 		this.uiContext = uiContext ?? noOpUIContext;
@@ -299,18 +307,23 @@ export class ExtensionRunner {
 	}
 
 	createContext(): ExtensionContext {
+		const getModel = this.getModel;
 		return {
 			ui: this.uiContext,
+			getContextUsage: () => this.getContextUsageFn(),
+			compact: (instructionsOrOptions) => this.compactFn(instructionsOrOptions),
 			hasUI: this.hasUI(),
 			cwd: this.cwd,
 			sessionManager: this.sessionManager,
 			modelRegistry: this.modelRegistry,
-			model: this.getModel(),
+			get model() {
+				return getModel();
+			},
 			isIdle: () => this.isIdleFn(),
 			abort: () => this.abortFn(),
 			hasPendingMessages: () => this.hasPendingMessagesFn(),
 			shutdown: () => this.shutdownHandler(),
-			hasQueuedMessages: () => this.hasPendingMessagesFn(),
+			hasQueuedMessages: () => this.hasPendingMessagesFn(), // deprecated alias
 		};
 	}
 
@@ -324,10 +337,12 @@ export class ExtensionRunner {
 	createCommandContext(): ExtensionCommandContext {
 		return {
 			...this.createContext(),
+			getContextUsage: () => this.getContextUsageFn(),
 			waitForIdle: () => this.waitForIdleFn(),
 			newSession: (options) => this.newSessionHandler(options),
 			branch: (entryId) => this.branchHandler(entryId),
 			navigateTree: (targetId, options) => this.navigateTreeHandler(targetId, options),
+			compact: (instructionsOrOptions) => this.compactFn(instructionsOrOptions),
 		};
 	}
 
@@ -446,6 +461,39 @@ export class ExtensionRunner {
 		return undefined;
 	}
 
+	/** Emit input event. Transforms chain, "handled" short-circuits. */
+	async emitInput(
+		text: string,
+		images: ImageContent[] | undefined,
+		source: "interactive" | "rpc" | "extension",
+	): Promise<InputEventResult> {
+		const ctx = this.createContext();
+		let currentText = text;
+		let currentImages = images;
+
+		for (const ext of this.extensions) {
+			for (const handler of ext.handlers.get("input") ?? []) {
+				try {
+					const event: InputEvent = { type: "input", text: currentText, images: currentImages, source };
+					const result = (await handler(event, ctx)) as InputEventResult | undefined;
+					if (result?.handled) return result;
+					if (result?.text !== undefined) {
+						currentText = result.text;
+						currentImages = result.images ?? currentImages;
+					}
+				} catch (err) {
+					this.emitError({
+						extensionPath: ext.path,
+						event: "input",
+						error: err instanceof Error ? err.message : String(err),
+						stack: err instanceof Error ? err.stack : undefined,
+					});
+				}
+			}
+		}
+		return currentText !== text || currentImages !== images ? { text: currentText, images: currentImages } : {};
+	}
+
 	async emitContext(messages: AgentMessage[]): Promise<AgentMessage[]> {
 		const ctx = this.createContext();
 		let currentMessages = structuredClone(messages);

package/src/core/extensions/types.ts

@@ -10,7 +10,7 @@
 
 import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, Model, TextContent, ToolResultMessage } from "@oh-my-pi/pi-ai";
-import type { Component, EditorComponent, EditorTheme, KeyId, TUI } from "@oh-my-pi/pi-tui";
+import type { AutocompleteItem, Component, EditorComponent, EditorTheme, KeyId, TUI } from "@oh-my-pi/pi-tui";
 import type { Static, TSchema } from "@sinclair/typebox";
 import type * as piCodingAgent from "../../index";
 import type { Theme } from "../../modes/interactive/theme/theme";
@@ -125,12 +125,30 @@ export interface ExtensionUIContext {
 // Extension Context
 // ============================================================================
 
+export interface ContextUsage {
+	tokens: number;
+	contextWindow: number;
+	percent: number;
+	usageTokens: number;
+	trailingTokens: number;
+	lastUsageIndex: number | null;
+}
+
+export interface CompactOptions {
+	onComplete?: (result: CompactionResult) => void;
+	onError?: (error: Error) => void;
+}
+
 /**
  * Context passed to extension event handlers.
  */
 export interface ExtensionContext {
 	/** UI methods for user interaction */
 	ui: ExtensionUIContext;
+	/** Get current context usage for the active model. */
+	getContextUsage(): ContextUsage | undefined;
+	/** Compact the session context (interactive mode shows UI). */
+	compact(instructionsOrOptions?: string | CompactOptions): Promise<void>;
 	/** Whether UI is available (false in print/RPC mode) */
 	hasUI: boolean;
 	/** Current working directory */
@@ -158,6 +176,9 @@ export interface ExtensionContext {
  * Includes session control methods only safe in user-initiated commands.
  */
 export interface ExtensionCommandContext extends ExtensionContext {
+	/** Get current context usage for the active model. */
+	getContextUsage(): ContextUsage | undefined;
+
 	/** Wait for the agent to finish streaming */
 	waitForIdle(): Promise<void>;
 
@@ -172,6 +193,9 @@ export interface ExtensionCommandContext extends ExtensionContext {
 
 	/** Navigate to a different point in the session tree. */
 	navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ cancelled: boolean }>;
+
+	/** Compact the session context (interactive mode shows UI). */
+	compact(instructionsOrOptions?: string | CompactOptions): Promise<void>;
 }
 
 // ============================================================================
@@ -382,6 +406,18 @@ export interface UserBashEvent {
 	cwd: string;
 }
 
+// ============================================================================
+// Input Events
+// ============================================================================
+
+/** Fired when the user submits input (interactive mode only). */
+export interface InputEvent {
+	type: "input";
+	text: string;
+	images?: ImageContent[];
+	source: "interactive" | "rpc" | "extension";
+}
+
 // ============================================================================
 // Tool Events
 // ============================================================================
@@ -486,6 +522,7 @@ export type ExtensionEvent =
 	| TurnStartEvent
 	| TurnEndEvent
 	| UserBashEvent
+	| InputEvent
 	| ToolCallEvent
 	| ToolResultEvent;
 
@@ -502,6 +539,16 @@ export interface ToolCallEventResult {
 	reason?: string;
 }
 
+/** Result from input event handler */
+export interface InputEventResult {
+	/** If true, the input was handled and should not continue through normal flow */
+	handled?: boolean;
+	/** Replace the input text */
+	text?: string;
+	/** Replace any pending images */
+	images?: ImageContent[];
+}
+
 /** Result from user_bash event handler */
 export interface UserBashEventResult {
 	/** Custom operations to use for execution */
@@ -565,6 +612,7 @@ export type MessageRenderer<T = unknown> = (
 export interface RegisteredCommand {
 	name: string;
 	description?: string;
+	getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null;
 	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
 }
 
@@ -622,6 +670,7 @@ export interface ExtensionAPI {
 	on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
 	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
 	on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
+	on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): void;
 	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
 	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
 	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
@@ -638,7 +687,14 @@ export interface ExtensionAPI {
 	// =========================================================================
 
 	/** Register a custom command. */
-	registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void;
+	registerCommand(
+		name: string,
+		options: {
+			description?: string;
+			getArgumentCompletions?: RegisteredCommand["getArgumentCompletions"];
+			handler: RegisteredCommand["handler"];
+		},
+	): void;
 
 	/** Register a keyboard shortcut. */
 	registerShortcut(
@@ -659,6 +715,9 @@ export interface ExtensionAPI {
 		},
 	): void;
 
+	/** Set the display label for this extension, or set a label on a specific entry. */
+	setLabel(entryIdOrLabel: string, label?: string | undefined): void;
+
 	/** Get the value of a registered CLI flag. */
 	getFlag(name: string): boolean | string | undefined;
 
@@ -776,6 +835,7 @@ export interface ExtensionActions {
 	sendMessage: SendMessageHandler;
 	sendUserMessage: SendUserMessageHandler;
 	appendEntry: AppendEntryHandler;
+	setLabel: (targetId: string, label: string | undefined) => void;
 	getActiveTools: GetActiveToolsHandler;
 	getAllTools: GetAllToolsHandler;
 	setActiveTools: SetActiveToolsHandler;
@@ -791,10 +851,13 @@ export interface ExtensionContextActions {
 	abort: () => void;
 	hasPendingMessages: () => boolean;
 	shutdown: () => void;
+	getContextUsage: () => ContextUsage | undefined;
+	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
 }
 
 /** Actions for ExtensionCommandContext (ctx.* in command handlers). */
 export interface ExtensionCommandContextActions {
+	getContextUsage: () => ContextUsage | undefined;
 	waitForIdle: () => Promise<void>;
 	newSession: (options?: {
 		parentSession?: string;
@@ -802,6 +865,7 @@ export interface ExtensionCommandContextActions {
 	}) => Promise<{ cancelled: boolean }>;
 	branch: (entryId: string) => Promise<{ cancelled: boolean }>;
 	navigateTree: (targetId: string, options?: { summarize?: boolean }) => Promise<{ cancelled: boolean }>;
+	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
 }
 
 /** Full runtime = state + actions. */
@@ -811,6 +875,7 @@ export interface ExtensionRuntime extends ExtensionRuntimeState, ExtensionAction
 export interface Extension {
 	path: string;
 	resolvedPath: string;
+	label?: string;
 	handlers: Map<string, HandlerFn[]>;
 	tools: Map<string, RegisteredTool>;
 	messageRenderers: Map<string, MessageRenderer>;