AgentSession: vòng đời một prompt

/** * AgentSession - Core abstraction for agent lifecycle and session management. * * This class is shared between all run modes (interactive, print, rpc). * It encapsulates: * - Agent state access * - Event subscription with automatic session persistence * - Model and thinking level management * - Compaction (manual and auto) * - Bash execution * - Session switching and branching * * Modes use this class and add their own I/O layer on top. */

// Always subscribe to agent events for internal handling// (session persistence, extensions, auto-compaction, retry logic)this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);this._installAgentToolHooks();this._installAgentNextTurnRefresh();this._installAgentRequestProjection();this._installAgentBoundaryHooks();this._installHiddenDeclarationsProjection();this._installAgentForcedPromptProjection();this._buildRuntime({	activeToolNames: this._initialActiveToolNames,	includeAllExtensionTools: true,});if (this._usesDefaultTools) this._restoreToolsFromTranscript(this._defaultToolModifiers);

export interface AgentSessionConfig {	agent: Agent;	sessionManager: SessionManager;	settingsManager: SettingsManager;	cwd: string;	/** Models to cycle through with Ctrl+P (from --models flag) */	scopedModels?: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>;	/** Resource loader for extensions, skills, prompts, themes, context files, and system prompt */	resourceLoader: ResourceLoader;	/** SDK custom tools registered outside extensions */	customTools?: ToolDefinition[];	/** Canonical model/auth runtime used by coding-agent internals. */	modelRuntime: ModelRuntime;	/** Keeps the prompt cache entry of the last session request warm. */	cacheWarmer?: Pick<CacheWarmer, "cancel" | "status" | "onAgentSettled" | "onModeChanged" | "onWarmed">;	/** Initial active built-in tool names. Default: [read, bash, edit, write] */	initialActiveToolNames?: string[];⋯ lược bớt dòng 269–295	/** Mutable ref used by Agent to access the current ExtensionRunner */	extensionRunnerRef?: { current?: ExtensionRunner };	/** Session start event metadata emitted when extensions bind to this runtime. */	sessionStartEvent?: SessionStartEvent;}

export type AgentSessionEvent =	| WithParentToolCallId<Exclude<AgentEvent, { type: "agent_end" }>>	| {			type: "agent_end";			messages: AgentMessage[];			willRetry: boolean;	  }	| { type: "agent_settled"; aborted: boolean }	| {			type: "queue_update";			steering: readonly string[];			followUp: readonly string[];	  }	| { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }	| { type: "entry_appended"; entry: SessionEntry }	| { type: "session_info_changed"; name: string | undefined }	| { type: "thinking_level_changed"; level: ThinkingLevel }	| {			type: "compaction_end";			reason: "manual" | "threshold" | "overflow";			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 }⋯ lược bớt dòng 223–236	| { type: "bash_execution_update"; id?: string; delta: string };

/** Options for AgentSession.prompt() */export interface PromptOptions {	/** Whether to dispatch extension commands and expand skill commands and prompt templates (default: true) */	expandPromptTemplates?: boolean;	/** Image attachments */	images?: ImageContent[];	/** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */	streamingBehavior?: "steer" | "followUp";	/** Source of input for extension input event handlers. Defaults to "interactive". */	source?: InputSource;	/** Internal hook used by RPC mode to observe how an accepted prompt was dispatched. Not called if the prompt is rejected. */	preflightResult?: (disposition: PromptDisposition) => void;}

/** * Message type for bash executions via the ! command. */export interface BashExecutionMessage {	role: "bashExecution";	command: string;	output: string;	exitCode: number | undefined;	cancelled: boolean;	truncated: boolean;	fullOutputPath?: string;	timestamp: number;	/** If true, this message is excluded from LLM context (!! prefix) */	excludeFromContext?: boolean;}/** * Message type for extension-injected messages via sendMessage(). * These are custom messages that extensions can inject into the conversation. */export interface CustomMessage<T = unknown> {	role: "custom";	customType: string;	content: string | (TextContent | ImageContent)[];	display: boolean;	details?: T;	timestamp: number;}

export interface BranchSummaryMessage {	role: "branchSummary";	summary: string;	fromId: string | null;	timestamp: number;}export interface CompactionSummaryMessage {	role: "compactionSummary";	summary: string;	tokensBefore: number;	timestamp: number;}// Extend CustomAgentMessages via declaration mergingdeclare module "@earendil-works/pi-agent-core" {	interface CustomAgentMessages {		bashExecution: BashExecutionMessage;		custom: CustomMessage;		branchSummary: BranchSummaryMessage;		compactionSummary: CompactionSummaryMessage;	}}

export function convertToLlm(messages: AgentMessage[]): Message[] {	return messages		.map((m): Message | undefined => {			switch (m.role) {				case "bashExecution":					// Skip messages excluded from context (!! prefix)					if (m.excludeFromContext) {						return undefined;					}					return {						role: "user",						content: [{ type: "text", text: bashExecutionToText(m) }],						timestamp: m.timestamp,					};				case "custom": {					const content = typeof m.content === "string" ? [{ type: "text" as const, text: m.content }] : m.content;					return {						role: "user",						content,						timestamp: m.timestamp,					};				}				case "branchSummary":					return {						role: "user",						content: [{ type: "text" as const, text: BRANCH_SUMMARY_PREFIX + m.summary + BRANCH_SUMMARY_SUFFIX }],						timestamp: m.timestamp,					};				case "compactionSummary":					return {						role: "user",						content: [							{ type: "text" as const, text: COMPACTION_SUMMARY_PREFIX + m.summary + COMPACTION_SUMMARY_SUFFIX },						],						timestamp: m.timestamp,					};

/** * Coherent cwd-bound runtime services for one effective session cwd. * * This is infrastructure only. The AgentSession itself is created separately so * session options can be resolved against these services first. */export interface AgentSessionServices {	cwd: string;	agentDir: string;	modelRuntime: ModelRuntime;	settingsManager: SettingsManager;	resourceLoader: ResourceLoader;	diagnostics: AgentSessionRuntimeDiagnostic[];}

export async function createAgentSessionServices(	options: CreateAgentSessionServicesOptions,): Promise<AgentSessionServices> {	const cwd = resolvePath(options.cwd);	const agentDir = options.agentDir ? resolvePath(options.agentDir) : getAgentDir();	const modelRuntime =		options.modelRuntime ??		(await ModelRuntime.create({			authPath: join(agentDir, "auth.json"),			modelsPath: join(agentDir, "models.json"),			signal: options.modelRuntimeSignal,		}));	const settingsManager = options.settingsManager ?? SettingsManager.create(cwd, agentDir);	const resourceLoader = new DefaultResourceLoader({		...(options.resourceLoaderOptions ?? {}),		cwd,		agentDir,		settingsManager,	});	await resourceLoader.reload(options.resourceLoaderReloadOptions);⋯ lược bớt dòng 155–193	await modelRuntime.refresh({ allowNetwork: false });	diagnostics.push(...applyExtensionFlagValues(resourceLoader, options.extensionFlagValues));	return {		cwd,		agentDir,		modelRuntime,		settingsManager,		resourceLoader,		diagnostics,	};}

// Check if session has existing data to restoreconst existingSession = sessionManager.buildSessionContext();const hasExistingSession = existingSession.messages.length > 0;const hasThinkingEntry = sessionManager.getBranch().some((entry) => entry.type === "thinking_level_change");let model = options.model;let modelFallbackMessage: string | undefined;// Assistant messages name the physical model that answered, so a virtual selection is only in// model_change entries.const sessionModel = getBranchSelection(sessionManager.getBranch(), (provider, modelId) =>	modelRuntime.getModel(provider, modelId),);// If session has data, try to restore model from itif (!model && hasExistingSession && sessionModel) {	const restoredModel = modelRuntime.getModel(sessionModel.provider, sessionModel.modelId);	if (restoredModel && modelRuntime.hasConfiguredAuth(restoredModel.provider)) {		model = restoredModel;	}	if (!model) {		modelFallbackMessage = `Could not restore model ${sessionModel.provider}/${sessionModel.modelId}`;	}}

const agent = new Agent({	initialState: {		systemPrompt: "",		model,		thinkingLevel,		tools: [],		messages: existingSession.messages,	},	convertToLlm: convertToLlmWithBlockImages,	streamFn: async (model, context, options) => {		const requestOptions = buildRequestOptions(options);		// Compaction and summaries use their own routing ids; only session requests		// replace the cache entry, so warming restarts from them. Keep warming while		// the current transcript still extends the request's prefix. Agent state may		// shallow-copy the messages array or refresh the model object without changing		// the provider request, so top-level object identity is not a valid cache key.		if (options?.sessionId === sessionManager.getSessionId()) {			cacheWarmer.start({ model, context, options: requestOptions }, cacheContextIsCurrent(model));		}		return modelRuntime.streamSimple(model, context, requestOptions);	},	onPayload: transformProviderPayload,	onResponse: handleProviderResponse,	onProviderStreamEvent: handleProviderStreamEvent,	sessionId: sessionManager.getSessionId(),	transformContext: async (messages) => {		const runner = extensionRunnerRef.current;		if (!runner) return messages;		return runner.emitContext(messages);	},	steeringMode: settingsManager.getSteeringMode(),	followUpMode: settingsManager.getFollowUpMode(),	transport: settingsManager.getTransport(),	thinkingBudgets: settingsManager.getThinkingBudgets(),	maxRetryDelayMs: settingsManager.getProviderRetrySettings().maxRetryDelayMs,});

// Restore missing settings metadata for older sessions.if (hasExistingSession) {	if (!hasThinkingEntry) {		sessionManager.appendThinkingLevelChange(thinkingLevel);	}} else {	// Save initial model and thinking level for new sessions so they can be restored on resume	if (model) {		sessionManager.appendModelChange(model.provider, model.id);	}	sessionManager.appendThinkingLevelChange(thinkingLevel);}

private async teardownCurrent(reason: SessionShutdownEvent["reason"], targetSessionFile?: string): Promise<void> {	// Settle any active response first so the aborted turn (including tool	// results) is persisted to the outgoing session before it is replaced.	await this.session.abort();	await emitSessionShutdownEvent(this.session.extensionRunner, {		type: "session_shutdown",		reason,		targetSessionFile,	});	this.beforeSessionInvalidate?.();	this.session.dispose();}⋯ lược bớt dòng 179–208	const previousSessionFile = this.session.sessionFile;	const sessionManager = SessionManager.open(sessionPath, undefined, options?.cwdOverride);	assertSessionCwdExists(sessionManager, this.cwd);	await this.teardownCurrent("resume", sessionManager.getSessionFile());	this.apply(		await this.createRuntime({			cwd: sessionManager.getCwd(),			agentDir: this.services.agentDir,			sessionManager,			sessionStartEvent: { type: "session_start", reason: "resume", previousSessionFile },			projectTrustContext: options?.projectTrustContextFactory?.(sessionManager.getCwd()),		}),	);	await this.finishSessionReplacement(options?.withSession);	return { cancelled: false };}

const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);if (mimeType) {	// Handle image file	const content = await readFile(absolutePath);	const processed = await processImage(content, mimeType, { autoResizeImages });	if (!processed.ok) {		text += `<file name="${absolutePath}">${processed.message}</file>\n`;		continue;	}	const attachment: ImageContent = {		type: "image",		mimeType: processed.mimeType,		data: processed.data,	};	images.push(attachment);	// Add text reference to image with optional processing hints	if (processed.hints.length > 0) {		text += `<file name="${absolutePath}">${processed.hints.join("\n")}</file>\n`;	} else {		text += `<file name="${absolutePath}"></file>\n`;	}} else {	// Handle text file	try {		const content = stripBom(await readFile(absolutePath, "utf-8"));		text += `<file name="${absolutePath}">\n${content}\n</file>\n`;

private _expandSkillCommand(text: string): string {	if (!text.startsWith("/skill:")) return text;	const spaceIndex = text.indexOf(" ");	const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);	const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();	const skill = this.resourceLoader.getSkills().skills.find((s) => s.name === skillName);	if (!skill) return text; // Unknown skill, pass through	try {		const content = readFileSync(skill.filePath, "utf-8");		const body = stripFrontmatter(content).trim();		const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;		return args ? `${skillBlock}\n\n${args}` : skillBlock;

	// If streaming, queue via steer() or followUp() based on option	if (this.isStreaming) {		if (!options?.streamingBehavior) {			throw new Error(				"Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.",			);		}		if (options.streamingBehavior === "followUp") {			await this._queueFollowUp(expandedText, currentImages);		} else {			await this._queueSteer(expandedText, currentImages);		}		preflightResult?.("queued");		return;	}	// Validate model	if (!this.model) {		throw new Error(formatNoModelSelectedMessage());	}	const hasConfiguredAuth =		this._modelRuntime.hasConfiguredAuth(this.model.provider) ||		(await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;	if (!hasConfiguredAuth) {		const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);		if (isOAuth) {			throw new Error(				`Authentication failed for "${this.model.provider}". ` +					`Credentials may have expired or network is unavailable. ` +					`Run '/login ${this.model.provider}' to re-authenticate.`,			);		}		throw new Error(formatNoApiKeyFoundMessage(this.model.provider));	}	await this._startRun({ messageType: "user", prompt: expandedText, images: currentImages }, () =>		preflightResult?.("started"),	);}

private async _startRun(trigger: BeforeAgentStartTrigger, onStarted?: () => void): Promise<void> {	this._isAgentRunActive = true;	this._agentRunAbortRequested = false;	let messages: AgentMessage[];	try {		messages = await this._prepareRun(trigger);	} catch (error) {		this._isAgentRunActive = false;		this._flushPendingBashMessages();		this._flushPendingCustomMessages();		this._resolveIdleWaitIfIdle();		throw error;	}	// Messages held while the run was starting go before its starting messages, as they would	// have while idle. No run exists yet, so they cannot split a tool call from its result.	this._flushPendingBashMessages();	this._flushPendingCustomMessages();	onStarted?.();	// Compaction before the prompt may have scheduled a retry; the new prompt replaces it.	this._failedResponse = undefined;	this._recordSelection();	// The run records the loadout in the transcript; restored tools that did not register by now	// are dropped, so a tool that never registers does not stay pending.	this._pendingToolNames.clear();

try {	await this.agent.prompt(messages);	while (!this._agentRunAbortRequested) {		if (await this._handlePostAgentRun()) {			if (this._agentRunAbortRequested) break;			await this.agent.continue();			continue;		}		if (this._agentRunAbortRequested || !(await this._runBeforeSettleBoundary())) break;		if (this._agentRunAbortRequested) break;		await this.agent.continue();	}} finally {	if (this._agentRunAbortRequested) this._finishCancelledRetry();	this._failedResponse = undefined;	this._runSystemPromptOptions = undefined;	this._flushPendingBashMessages();	this._flushPendingCustomMessages();	await this._emitAgentSettled();}

private async _prepareRun(trigger: BeforeAgentStartTrigger): Promise<AgentMessage[]> {	// Check if we need to compact before sending (catches aborted responses).	// The starting message is sent below, so do not call agent.continue() here.	const lastAssistant = this._findLastAssistantMessage();	if (lastAssistant) {		await this._checkCompaction(lastAssistant, false);	}	const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;	const result = await this._extensionRunner.emitBeforeAgentStart(trigger, this._baseSystemPromptOptions);	// Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),	// which updates the live loadout instead. An explicit edit wins; otherwise the live	// loadout is authoritative, so a setActiveTools() call is not undone here.	const handlerEditedTools =		result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||		result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);	if (!handlerEditedTools) result.systemPromptOptions.selectedTools = this.getActiveToolNames();

const messages: AgentMessage[] = [];if (trigger.messageType === "custom") {	messages.push(trigger.message);} else {	// Normalize images after before_agent_start so extension-driven model selection	// determines the resize profile used for the request and history.	const normalized = await this._normalizePromptImages(trigger.images);	const text =		normalized.hints.length > 0 ? `${trigger.prompt}\n\n${normalized.hints.join("\n")}` : trigger.prompt;	messages.push({		role: "user",		content: [{ type: "text", text }, ...normalized.images],		timestamp: Date.now(),	});}// Inject any pending "nextTurn" messages as context alongside the starting messagemessages.push(...this._pendingNextTurnMessages);this._pendingNextTurnMessages = [];for (const msg of result.messages) {	messages.push({		role: "custom",		customType: msg.customType,		// Untyped extensions can pass null/missing content; normalize at ingestion.		content: msg.content ?? [],		display: msg.display,		details: msg.details,		timestamp: Date.now(),	});}const updateMessage = this._preparePromptAndToolLoadout(result.systemPromptOptions);this._runSystemPromptOptions = result.systemPromptOptions;if (updateMessage) messages.unshift(updateMessage);return messages;

private _preparePromptAndToolLoadout(	options: NormalizedBuildSystemPromptOptions,	messages: AgentMessage[] = this.agent.state.messages,): SystemMessage | undefined {	options.selectedTools = this._applyToolLoadout(options.selectedTools).map((tool) => tool.name);	// The tool list and rules must match the declarations the request carries.	options.hiddenTools = [...this._hiddenDeclarations];	const sections = diffSystemPromptSections(		getCurrentSystemMessage(messages)?.sections ?? {},		buildSystemPromptSections(options),	);	return sections ? { role: "system", content: "", sections, timestamp: Date.now() } : undefined;}

private async _handlePostAgentRun(): Promise<boolean> {	const message = this._lastAssistantMessage;	this._lastAssistantMessage = undefined;	if (this._agentRunAbortRequested) {		this._finishCancelledRetry();		return false;	}	if (!message) return this.agent.hasQueuedMessages();	if (this._isRetryableError(message) && (await this._prepareRetry(message))) {		if (this._agentRunAbortRequested) this._finishCancelledRetry();		this._failedResponse = message;		return !this._agentRunAbortRequested;	}	if (this._agentRunAbortRequested) {		this._finishCancelledRetry();		return false;	}	if (message.stopReason === "error" && this._retryAttempt > 0) {		this._emit({			type: "auto_retry_end",			success: false,			attempt: this._retryAttempt,			finalError: message.errorMessage,		});		this._retryAttempt = 0;	}	if (await this._checkCompaction(message)) {		return !this._agentRunAbortRequested;	}	// The low-level loop drains both queues before agent_end. Messages queued by	// agent_end handlers require a fresh run before pre-settlement handlers fire.	return !this._agentRunAbortRequested && this.agent.hasQueuedMessages();}

private _handleAgentEvent = async (event: AgentEvent): Promise<void> => {	// An abort requested while the run was starting, e.g. during before_agent_start, stops it	// here. agent_start is awaited before the first request.	if (event.type === "agent_start" && this._agentRunAbortRequested) this.agent.abort();⋯ lược bớt dòng 1107–1119	// When a user message starts, check if it's from either queue and remove it BEFORE emitting	// This ensures the UI sees the updated queue state	if (event.type === "message_start" && event.message.role === "user") {		this._overflowRecoveryAttempted = false;		const messageText = contentText(event.message.content, "");		if (messageText) {			// Check steering queue first			const steeringIndex = this._steeringMessages.indexOf(messageText);			if (steeringIndex !== -1) {				this._steeringMessages.splice(steeringIndex, 1);				this._emitQueueUpdate();			} else {				// Check follow-up queue				const followUpIndex = this._followUpMessages.indexOf(messageText);				if (followUpIndex !== -1) {					this._followUpMessages.splice(followUpIndex, 1);					this._emitQueueUpdate();				}			}		}	}	// Emit to extensions first, then notify public listeners.	await this._emitExtensionEvent(event);	this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);

} else if (event.type === "message_end") {	const extensionEvent: MessageEndEvent = {		type: "message_end",		message: event.message,	};	const replacement = await this._extensionRunner.emitMessageEnd(extensionEvent);	if (replacement) {		// Untyped extension handlers can return messages with null/missing content;		// normalize so it never enters agent state or session history.		const normalized =			(replacement.role === "user" ||				replacement.role === "assistant" ||				replacement.role === "toolResult" ||				replacement.role === "custom") &&			replacement.content == null				? ({ ...replacement, content: [] } as AgentMessage)				: replacement;		this._replaceMessageInPlace(event.message, normalized);	}

// Handle session persistenceif (event.type === "message_end") {	let entryId: string | undefined;	// Check if this is a custom message from extensions	if (event.message.role === "custom") {		// Persist as CustomMessageEntry		entryId = this.sessionManager.appendCustomMessageEntry(			event.message.customType,			event.message.content,			event.message.display,			event.message.details,		);	} else if (		event.message.role === "system" ||		event.message.role === "user" ||		event.message.role === "assistant" ||		event.message.role === "toolResult"	) {		// Regular LLM message - persist as SessionMessageEntry		entryId = this.sessionManager.appendMessage(event.message);	}	if (entryId) this._entryIdsByMessage.set(event.message, entryId);	// Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere⋯ lược bớt dòng 1169–1189// A turn ends after its assistant message and every tool result has been appended,// so this is the first point in the run where a context-only custom message can be// inserted without landing between a tool call and its result. Flushing after the// extension and listener dispatch above also picks up messages that turn_end// handlers queued.if (event.type === "turn_end") {	this._flushPendingCustomMessages();}

private _installAgentRequestProjection(): void {	const previousPrepareRequest = this.agent.prepareRequest;	this.agent.prepareRequest = async (request, signal) => {		const failed = this._failedResponse;		this._failedResponse = undefined;		const prepare = async () => {			const projection = this.sessionManager.buildSessionProjection();			const canonicalContext = {				...request.context,				messages: projection.messages,				// Messages declare the provider-visible loadout; context.tools keeps executable implementations.				tools: this.agent.state.tools.slice(),			};			const previous = await previousPrepareRequest?.(				{					...request,					context: canonicalContext,					model: this.agent.state.model,					thinkingLevel: this.agent.state.thinkingLevel,				},				signal,			);			return { previous, context: previous?.context ?? canonicalContext, projection };		};		let { previous, context, projection } = await prepare();		const model = previous?.model ?? this.agent.state.model;		const thinkingLevel = previous?.thinkingLevel ?? this.agent.state.thinkingLevel;		if (!isVirtualModel(model)) return { ...previous, context, model, thinkingLevel };

this.agent.prepareNextTurnWithContext = async (turn, signal) => {	const context = await this._compactBeforeNextAssistantResponse(turn.context);	const previousSnapshot = await previousPrepareNextTurnWithContext?.({ ...turn, context }, signal);	const nextContext = previousSnapshot?.context ?? context;	const runOptions = this._runSystemPromptOptions ?? this._baseSystemPromptOptions;	const options = normalizeBuildSystemPromptOptions({		...runOptions,		selectedTools: this.getActiveToolNames(),		toolSnippets: { ...this._baseSystemPromptOptions.toolSnippets, ...runOptions.toolSnippets },		toolGuidelines: { ...this._baseSystemPromptOptions.toolGuidelines, ...runOptions.toolGuidelines },	});	const updateMessage = this._preparePromptAndToolLoadout(options, nextContext.messages);	// Keep session.systemPrompt and ctx.getSystemPrompt() in step with what the provider sees.	this._runSystemPromptOptions = options;	return {		...previousSnapshot,		context: {			...nextContext,			tools: this.agent.state.tools.slice(),		},		messages: updateMessage			? [...(previousSnapshot?.messages ?? []), updateMessage]			: previousSnapshot?.messages,		model: this.agent.state.model,		thinkingLevel: this.agent.state.thinkingLevel,	};};

/** * Check if an error is retryable (overloaded, rate limit, server errors). * Context overflow errors are NOT retryable (handled by compaction instead). */private _isRetryableError(message: AssistantMessage): boolean {	// Context overflow is handled by compaction, not retry.	if (isContextOverflow(message, (this._modelForMessage(message) ?? this.model)?.contextWindow ?? 0)) return false;	return isRetryableAssistantError(message);}

private async _prepareRetry(message: AssistantMessage): Promise<boolean> {	const settings = this.settingsManager.getRetrySettings();	if (!settings.enabled) {		return false;	}	this._retryAttempt++;	if (this._retryAttempt > settings.maxRetries) {		// Preserve the completed attempt count so post-run handling can emit the final failure.		this._retryAttempt--;		return false;	}	const delayMs = retryDelayMs(settings, this._retryAttempt);	this._emit({		type: "auto_retry_start",		attempt: this._retryAttempt,		maxAttempts: settings.maxRetries,		delayMs,		errorMessage: message.errorMessage || "Unknown error",	});	// Keep the failed attempt in raw history while durably omitting it from model projection.	this._omitRecoveryAttempt(message);	// Wait with exponential backoff (abortable)	this._retryAbortController = new AbortController();	try {		await sleep(delayMs, this._retryAbortController.signal);	} catch {		// Aborted during sleep - emit end event so UI can clean up		this._finishCancelledRetry();		return false;	} finally {		this._retryAbortController = undefined;	}	return true;

/** * Persistently omit a failed attempt and its tool results from model context. Results are * found in the projected context, so the pair stays together whether the attempt comes from * the current run or a resumed session. An unpaired result fails the next request (#11227). */private _omitRecoveryAttempt(message: AssistantMessage): void {	const toolCallIds = new Set(message.content.flatMap((block) => (block.type === "toolCall" ? [block.id] : [])));	// A context edit replaces the projected copy, so match it by source entry as well.	const entryId = this._findPersistedMessageEntryId(message);	const messages = this.agent.state.messages;	const index = messages.findIndex(		(m) => m === message || (entryId !== undefined && this._entryIdsByMessage.get(m) === entryId),	);	const toolResults: AgentMessage[] = [];	for (const m of index < 0 ? [] : messages.slice(index + 1)) {		if (m.role === "assistant") break;		if (m.role === "toolResult" && toolCallIds.has(m.toolCallId)) toolResults.push(m);	}	const targets = [message, ...toolResults];	const targetIds = targets.map((target) => this._findPersistedMessageEntryId(target));	const unresolvedProjectedTarget = targets.some(		(target, index) => targetIds[index] === undefined && this.agent.state.messages.includes(target),	);	if (unresolvedProjectedTarget) {		throw new Error("Cannot persist recovery omission because a projected message has no source entry");	}	for (const targetId of targetIds) {		if (!targetId) continue;		const editId = this.sessionManager.appendContextEdit(targetId, null);		const entry = this.sessionManager.getEntry(editId);		if (entry) this._emit({ type: "entry_appended", entry });	}	this._refreshFinalizedContext();}

 * Automatic cases: * 1. Overflow with retry: a context-overflow error or recoverable length stop; *    remove the failed assistant message, compact, and retry the turn once. * 2. Overflow without retry: a successful response exceeded the configured *    context window; compact but preserve the completed response. * 3. Threshold without retry: valid or estimated context usage crossed the *    configured threshold; compact without retrying the completed response.⋯ lược bớt dòng 3001–3010private async _checkCompaction(assistantMessage: AssistantMessage, skipAbortedCheck = true): Promise<boolean> {	const settings = this.settingsManager.getCompactionSettings(this.model);	if (!settings.enabled) return false;	// Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false	if (skipAbortedCheck && assistantMessage.stopReason === "aborted") return false;	// Skip overflow check if the message came from a different model.	// This handles the case where user switched from a smaller-context model (e.g. opus)	// to a larger-context model (e.g. codex) - the overflow error from the old model	// shouldn't trigger compaction for the new model. Under a virtual selection, the	// physical model that produced the message supplies the limits.	const messageModel = this._modelForMessage(assistantMessage);	const sameModel = messageModel !== undefined;	const contextWindow = (messageModel ?? this.model)?.contextWindow ?? 0;	// Skip compaction checks if this assistant message is older than the latest	// compaction boundary. This prevents a stale pre-compaction usage/error	// from retriggering compaction on the first prompt after compaction.	const compactionEntry = getLatestCompactionEntry(this.sessionManager.getBranch());	const assistantIsFromBeforeCompaction =		compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();	if (assistantIsFromBeforeCompaction) {		return false;	}

if (contextOverflow || recoverableLength) {	const willRetry = assistantMessage.stopReason !== "stop";	// Case 2: the response completed successfully. Compact, but do not retry because	// agent.continue() cannot continue from a completed assistant response.	if (!willRetry) {		return await this._runAutoCompaction("overflow", false);	}	if (this._overflowRecoveryAttempted) {		const errorMessage = contextOverflow			? "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model."			: "Truncated response recovery failed after one compact-and-retry attempt.";		this._emit({			type: "compaction_end",			reason: "overflow",			result: undefined,			aborted: false,			willRetry: false,			errorMessage,		});		await this._emitSessionCompactFailed({			reason: "overflow",			errorMessage,			aborted: false,			willRetry: false,			fromExtension: false,		});		return false;	}	// Persistently omit the selected final attempt before post-run recovery compaction.	this._overflowRecoveryAttempted = true;	this._omitRecoveryAttempt(assistantMessage);	const retry = await this._runAutoCompaction("overflow", willRetry);	if (retry) this._failedResponse = assistantMessage;	return retry;

private async _compactBeforeNextAssistantResponse(context: AgentContext): Promise<AgentContext> {	const projection = this.sessionManager.buildSessionProjection();	// A virtual selection is checked in prepareRequest, against the model the request is routed to.	const model = this.model;	if (!model || isVirtualModel(model) || !this._exceedsCompactionThreshold(model, projection)) {		return { ...context, messages: projection.messages };	}	await this._runAutoCompaction("threshold", false);	return { ...context, messages: this.sessionManager.buildSessionProjection().messages };}

async setModel(model: Model<any>, options: ModelMutationOptions = {}): Promise<void> {	if (!(await this._modelRuntime.checkAuth(model.provider))) {		throw new Error(`No API key for ${model.provider}/${model.id}`);	}	const previousModel = this.model;	const thinkingLevel = this._getThinkingLevelForModelSwitch(model);	this.agent.state.model = model;	this.sessionManager.appendModelChange(model.provider, model.id);	if (options.persist) {		this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);		this._addPersistedDefaultToNonEmptyScope(model);	}	// Apply thinking level for the new model.	// Per-model thinking level overrides take priority over the global default.	// Model persistence does not implicitly rewrite the global thinking default.	this.setThinkingLevel(thinkingLevel);	await this._emitModelSelect(model, previousModel, "set");}

setThinkingLevel(level: ThinkingLevel, options: ModelMutationOptions = {}): void {	const availableLevels = this.getAvailableThinkingLevels();	const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);	// Only persist if actually changing	const previousLevel = this.agent.state.thinkingLevel;	const isChanging = effectiveLevel !== previousLevel;	this.agent.state.thinkingLevel = effectiveLevel;	if (options.persist) {		this.settingsManager.setDefaultThinkingLevel(level);	}	if (isChanging) {		this.sessionManager.appendThinkingLevelChange(effectiveLevel);		this._emit({ type: "thinking_level_changed", level: effectiveLevel });		void this._extensionRunner.emit({			type: "thinking_level_select",			level: effectiveLevel,			previousLevel,		});	}}

private async _queueSteer(text: string, images?: ImageContent[]): Promise<void> {	this._steeringMessages.push(text);	this._emitQueueUpdate();	const content: (TextContent | ImageContent)[] = [{ type: "text", text }];	if (images) {		content.push(...images);	}	this.agent.steer({		role: "user",		content,		timestamp: Date.now(),	});}/** * Internal: Queue a follow-up message (already expanded, no extension command check). */private async _queueFollowUp(text: string, images?: ImageContent[]): Promise<void> {	this._followUpMessages.push(text);	this._emitQueueUpdate();	const content: (TextContent | ImageContent)[] = [{ type: "text", text }];	if (images) {		content.push(...images);	}	this.agent.followUp({ role: "user", content, timestamp: Date.now() });}

async abort(): Promise<void> {	if (this._isAgentRunActive) {		this._agentRunAbortRequested = true;	}	this.abortRetry();	this.abortCompaction();	this.abortBranchSummary();	if (this._isBeforeSettle) this._abortDuringBeforeSettle = true;	this.agent.abort();	await this.waitForIdle();}

async sendCustomMessage<T = unknown>(	message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,	options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },): Promise<void> {	const appMessage = {		role: "custom" as const,		customType: message.customType,		// Untyped extensions can pass null/missing content; normalize at ingestion.		content: message.content ?? [],		display: message.display,		details: message.details,		timestamp: Date.now(),	} satisfies CustomMessage<T>;	if (options?.deliverAs === "nextTurn") {		this._pendingNextTurnMessages.push(appMessage);	} else if (this.isStreaming && options?.triggerTurn !== false) {		if (options?.deliverAs === "followUp") {			this.agent.followUp(appMessage);		} else {			this.agent.steer(appMessage);		}	} else if (options?.triggerTurn) {		if (this._isEmittingAgentSettled) {			this._deferredSettledActions.push(async () => await this.sendCustomMessage(message, options));			return;		}		await this._startRun({ messageType: "custom", message: appMessage });	} else if (this.isStreaming) {		// Appending now would put the message between an assistant tool call and its		// result, which providers that validate message order reject on replay. Defer		// to the end of the turn. Nothing is emitted yet: message events must not		// describe messages the session tree does not contain.		this._pendingCustomMessages.push(appMessage);	} else {		this._appendCustomMessage(appMessage);	}}

// Handle bash command (! for normal, !! for excluded from context)if (text.startsWith("!")) {	const isExcluded = text.startsWith("!!");	const command = isExcluded ? text.slice(2).trim() : text.slice(1).trim();	if (command) {		if (this.session.isBashRunning) {			this.showWarning("A bash command is already running. Press Esc to cancel it first.");			this.editor.setText(text);			return;		}		this.editor.addToHistory?.(text);		await this.handleBashCommand(command, isExcluded);		this.isBashMode = false;		this.updateEditorBorderColor();		return;	}}

async executeBash(	command: string,	onChunk?: (chunk: string) => void,	options?: { excludeFromContext?: boolean; id?: string; operations?: BashOperations },): Promise<BashResult> {	const abortController = new AbortController();	this._bashAbortControllers.add(abortController);	// Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)	const prefix = this.settingsManager.getShellCommandPrefix();	const shellPath = this.settingsManager.getShellPath();	const resolvedCommand = prefix ? `${prefix}\n${command}` : command;	try {		const result = await executeBashWithOperations(			resolvedCommand,			this.sessionManager.getCwd(),			options?.operations ?? createLocalBashOperations({ shellPath }),			{				onChunk: (delta) => {					onChunk?.(delta);					this._emit({ type: "bash_execution_update", id: options?.id, delta });				},				signal: abortController.signal,			},		);		this.recordBashResult(command, result, options);		return result;	} finally {		this._bashAbortControllers.delete(abortController);	}}

	// Start writing to temp file if exceeds threshold	if (totalBytes > DEFAULT_MAX_BYTES) {		ensureTempFile();	}	if (tempFileStream) {		tempFileStream.write(text);	}	// Keep rolling buffer	outputChunks.push(text);	outputBytes += text.length;	while (outputBytes > maxOutputBytes && outputChunks.length > 1) {		const removed = outputChunks.shift()!;		outputBytes -= removed.length;	}⋯ lược bớt dòng 99–129flushOutput();const fullOutput = outputChunks.join("");const truncationResult = truncateTail(fullOutput);if (truncationResult.truncated) {	ensureTempFile();}tempFileStream?.end();const cancelled = options?.signal?.aborted ?? false;return {	output: truncationResult.truncated ? truncationResult.content : fullOutput,	exitCode: cancelled ? undefined : (exitCode ?? undefined),	cancelled,	truncated: truncationResult.truncated,	fullOutputPath: tempFilePath,};

recordBashResult(command: string, result: BashResult, options?: { excludeFromContext?: boolean }): void {	const bashMessage: BashExecutionMessage = {		role: "bashExecution",		command,		output: result.output,		exitCode: result.exitCode,		cancelled: result.cancelled,		truncated: result.truncated,		fullOutputPath: result.fullOutputPath,		timestamp: Date.now(),		excludeFromContext: options?.excludeFromContext,	};	// If agent is streaming, defer adding to avoid breaking tool_use/tool_result ordering	if (this.isStreaming) {		// Queue for later - will be flushed on agent_end		this._pendingBashMessages.push(bashMessage);	} else {		this.sessionManager.appendMessage(bashMessage);		this._refreshFinalizedContext();	}}

function isMergeableObject(value: unknown): value is Record<string, unknown> {	return typeof value === "object" && value !== null && !Array.isArray(value);}function deepMergeObjects(base: Record<string, unknown>, overrides: Record<string, unknown>): Record<string, unknown> {	const result = { ...base };	for (const key of Object.keys(overrides)) {		const overrideValue = overrides[key];		if (overrideValue === undefined) {			continue;		}		const baseValue = base[key];		result[key] =			isMergeableObject(baseValue) && isMergeableObject(overrideValue)				? deepMergeObjects(baseValue, overrideValue)				: overrideValue;	}	return result;}⋯ lược bớt dòng 83–141/** Deep merge settings: project/overrides take precedence, nested objects merge recursively */function deepMergeSettings(base: Settings, overrides: Settings): Settings {	const merged = deepMergeObjects(base as Record<string, unknown>, overrides as Record<string, unknown>) as Settings;	const defaultTools = mergeDefaultTools(base.defaultTools, overrides.defaultTools);	return defaultTools === undefined ? merged : { ...merged, defaultTools };}

export async function refreshStoredOAuthCredential(	credentials: CredentialStore,	providerId: string,	oauth: OAuthAuth,	needsRefresh: (credential: OAuthCredential) => boolean,	signal: AbortSignal,): Promise<OAuthCredential | undefined> {	let post: Credential | undefined;	const lockWait = new AbortController();	const cancelLockWait = () => lockWait.abort(signal.reason);	signal.addEventListener("abort", cancelLockWait, { once: true });	if (signal.aborted) cancelLockWait();	try {		post = await credentials.modify(			providerId,			async (current) => {				signal.removeEventListener("abort", cancelLockWait);				signal.throwIfAborted();				if (current?.type !== "oauth") return undefined; // logged out meanwhile				if (!needsRefresh(current)) return undefined; // another process/request refreshed				try {					return await oauth.refresh(current, AbortSignal.timeout(DEFAULT_OAUTH_REFRESH_TIMEOUT_MS));				} catch (error) {					throw new ModelsError("oauth", `OAuth refresh failed for ${providerId}`, { cause: error });				}			},			{ signal: lockWait.signal },		);	} catch (error) {		if (error instanceof ModelsError) throw error;		signal.throwIfAborted();		throw new ModelsError("auth", `Credential store modify failed for ${providerId}`, { cause: error });	} finally {		signal.removeEventListener("abort", cancelLockWait);	}	return post?.type === "oauth" ? post : undefined;

// Important: use *all* models here, not just models with pre-configured auth.// This allows "--api-key" to be used for first-time setup.const models = [...modelRuntime.getModels()];if (models.length === 0) {	return {		model: undefined,		warning: undefined,		error: "No models available. Check your installation or add models to models.json.",	};}const provider = cliProvider	? models.find((m) => m.provider.toLowerCase() === cliProvider.toLowerCase())?.provider	: undefined;if (cliProvider && !provider) {	return {		model: undefined,		warning: undefined,		error: `Unknown provider "${cliProvider}". Use --list-models to see available providers/models.`,	};}const result = resolveModelReference(	{ text: cliModel, provider, thinkingSuffix: "strict", fuzzy: true },	models,	// An inline key goes to whichever provider is selected, so stored credentials must not choose it	inlineApiKey ? () => false : (providerId) => modelRuntime.hasConfiguredAuth(providerId),);

// 2. Try saved default from settings if auth is configured.if (defaultProvider && defaultModelId) {	const found = modelRuntime.getModel(defaultProvider, defaultModelId);	if (found && modelRuntime.hasConfiguredAuth(found.provider)) {		model = found;		const perModel = modelThinkingLevels?.[`${defaultProvider}/${defaultModelId}`];		if (perModel) {			thinkingLevel = perModel;		} else if (defaultThinkingLevel) {			thinkingLevel = defaultThinkingLevel;		}		return { model, thinkingLevel, fallbackMessage: undefined };	}}// 3. Try first available model with valid API keyconst availableModels = [...modelRuntime.getAvailableSnapshot()];if (availableModels.length > 0) {	// Try to find a default model from known providers	for (const provider of Object.keys(defaultModelPerProvider) as KnownProvider[]) {		const defaultId = defaultModelPerProvider[provider];		const match = availableModels.find((m) => m.provider === provider && m.id === defaultId);		if (match) {			return { model: match, thinkingLevel: DEFAULT_THINKING_LEVEL, fallbackMessage: undefined };		}	}	// If no default found, use first available	return { model: availableModels[0], thinkingLevel: DEFAULT_THINKING_LEVEL, fallbackMessage: undefined };}

async loadProjectTrustExtensions(): Promise<LoadExtensionsResult> {	// Force untrusted project settings for the bootstrap pass. This keeps project-local	// extensions/packages out while still loading user/global and temporary CLI extensions.	this.settingsManager.setProjectTrusted(false);	await this.settingsManager.reload();	return this.loadCurrentExtensionSet({ includeInlineFactories: true });}async reload(options?: ResourceLoaderReloadOptions): Promise<void> {	resetTimings("extensions");	if (this.loaded) {		clearExtensionCache();	}	let preTrustExtensions: LoadExtensionsResult | undefined;	if (options?.resolveProjectTrust) {		preTrustExtensions = await this.loadProjectTrustExtensions();		const projectTrusted = await options.resolveProjectTrust({ extensionsResult: preTrustExtensions });		this.settingsManager.setProjectTrusted(projectTrusted);	}	// reload() preserves SettingsManager.projectTrusted and reloads settings for that trust state.	await this.settingsManager.reload();

export async function resolveProjectTrusted(options: ResolveProjectTrustedOptions): Promise<boolean> {	if (options.trustOverride !== undefined) {		return options.trustOverride;	}	if (!hasTrustRequiringProjectResources(options.cwd)) {		return true;	}	if (options.extensionsResult) {		const { result, errors } = await emitProjectTrustEvent(			options.extensionsResult,			{ type: "project_trust", cwd: options.cwd },			options.projectTrustContext,		);		for (const error of errors) {			options.onExtensionError?.(`Extension "${error.extensionPath}" project_trust error: ${error.error}`);		}		if (result) {			const trusted = result.trusted === "yes";			if (result.remember === true) {				options.trustStore.set(options.cwd, trusted);			}			return trusted;		}	}	const decision = options.trustStore.get(options.cwd);	if (decision !== null) {		return decision;	}	switch (options.defaultProjectTrust ?? SETTINGS_DEFAULTS.defaultProjectTrust) {		case "always":			return true;		case "never":			return false;		case "ask":			break;	}