/** Agent class that uses the agent-loop directly.
 * No transport abstraction - calls streamSimple via the loop.
 */
import {
	type AssistantMessage,
	type AssistantMessageEvent,
	type CursorExecHandlers,
	type CursorToolResultHandler,
	type Effort,
	getBundledModel,
	type ImageContent,
	type Message,
	type Model,
	type ProviderSessionState,
	type ServiceTier,
	type SimpleStreamOptions,
	streamSimple,
	type TextContent,
	type ThinkingBudgets,
	type ToolChoice,
	type ToolResultMessage,
} from "@sayknow-cli/ai";
import { extractHttpStatusFromError } from "@sayknow-cli/utils";
import { agentLoop, agentLoopContinue } from "./agent-loop";
import type { AppendOnlyContextManager } from "./append-only-context";
import type { HarmonyAuditEvent } from "./harmony-leak";
import { assertImagePlaceholdersHavePayload } from "./image-placeholder-guard";
import type {
	AgentContext,
	AgentEvent,
	AgentLoopConfig,
	AgentMessage,
	AgentState,
	AgentTool,
	AgentToolContext,
	ManagedAttemptContinuation,
	ManagedAttemptContinuationOwnership,
	ManagedAttemptDecision,
	ManagedAttemptOutcome,
	ManagedLogicalRunId,
	RunTerminalRequest,
	StreamFn,
	ToolCallContext,
} from "./types";

function assertUserImagePlaceholdersHavePayload(messages: readonly AgentMessage[]): void {
	for (const message of messages) {
		if (!("role" in message) || message.role !== "user") continue;
		const content = message.content;
		if (typeof content === "string") {
			assertImagePlaceholdersHavePayload(content, undefined);
			continue;
		}
		if (!Array.isArray(content)) continue;
		const text = content
			.filter(part => part.type === "text")
			.map(part => part.text)
			.join("\n");
		assertImagePlaceholdersHavePayload(text, content);
	}
}

/**
 * Whether persisted history ends at a point where a new model turn can resume.
 * Assistant-ended histories require an in-memory queued message and are handled
 * separately by `Agent.continue()`.
 */
export function canContinuePersistedHistory(messages: readonly AgentMessage[]): boolean {
	const lastMessage = messages.at(-1);
	return lastMessage !== undefined && lastMessage.role !== "assistant";
}

/**
 * Default convertToLlm: Keep only LLM-compatible messages, convert attachments.
 */
function defaultConvertToLlm(messages: AgentMessage[]): Message[] {
	return messages.filter((m): m is Message => m.role === "user" || m.role === "assistant" || m.role === "toolResult");
}

function refreshToolChoiceForActiveTools(
	toolChoice: ToolChoice | undefined,
	tools: AgentContext["tools"] = [],
): ToolChoice | undefined {
	if (!toolChoice || typeof toolChoice === "string") {
		return toolChoice;
	}

	const toolName =
		toolChoice.type === "tool"
			? toolChoice.name
			: "function" in toolChoice
				? toolChoice.function.name
				: toolChoice.name;

	return tools.some(tool => tool.name === toolName) ? toolChoice : undefined;
}

export class ManagedCursorInvariantError extends Error {
	constructor(message: string = "Managed Cursor attempt received a provider-side tool result") {
		super(message);
		this.name = "ManagedCursorInvariantError";
	}
}

export class AgentBusyError extends Error {
	constructor(
		message: string = "Agent is already processing. Use steer() or followUp() to queue messages, or wait for completion.",
	) {
		super(message);
		this.name = "AgentBusyError";
	}
}
export interface AgentOptions {
	initialState?: Partial<AgentState>;

	/**
	 * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
	 * Default filters to user/assistant/toolResult and converts attachments.
	 */
	convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;

	/**
	 * Optional transform applied to context before convertToLlm.
	 * Use for context pruning, injecting external context, etc.
	 */
	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;

	/**
	 * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
	 */
	steeringMode?: "all" | "one-at-a-time";

	/**
	 * Follow-up mode: "all" = send all follow-up messages at once, "one-at-a-time" = one per turn
	 */
	followUpMode?: "all" | "one-at-a-time";

	/**
	 * When to interrupt tool execution for steering messages.
	 * - "immediate": check after each tool call (default)
	 * - "wait": defer steering until the current turn completes
	 */
	interruptMode?: "immediate" | "wait";
	/** Cooperative pause checkpoint passed through to AgentLoopConfig.shouldPause. */
	shouldPause?: AgentLoopConfig["shouldPause"];

	/**
	 * API format for Kimi Code provider: "openai" or "anthropic" (default: "anthropic")
	 */
	kimiApiFormat?: "openai" | "anthropic";

	/** Hint that websocket transport should be preferred when supported by the provider implementation. */
	preferWebsockets?: boolean;

	/**
	 * Custom stream function (for proxy backends, etc.). Default uses streamSimple.
	 */
	streamFn?: StreamFn;

	/**
	 * Optional session identifier forwarded to LLM providers.
	 * Used by providers that support session-based caching (e.g., OpenAI code provider).
	 */
	sessionId?: string;
	/** Provider-facing cache/session affinity identifier. */
	providerSessionId?: string;
	/**
	 * Shared provider state map for session-scoped transport/session caches.
	 */
	providerSessionState?: Map<string, ProviderSessionState>;

	/**
	 * Resolves an API key dynamically for each LLM call.
	 * Useful for expiring tokens (e.g., GitHub Copilot OAuth).
	 */
	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
	getAuthCredentialType?: (provider: string) => "api_key" | "oauth" | undefined;

	/**
	 * Inspect or replace provider payloads before they are sent.
	 */
	onPayload?: SimpleStreamOptions["onPayload"];
	/**
	 * Inspect provider response metadata after headers arrive and before streaming body consumption.
	 */
	onResponse?: SimpleStreamOptions["onResponse"];
	/**
	 * Inspect raw Server-Sent Events from HTTP streaming providers.
	 */
	onSseEvent?: SimpleStreamOptions["onSseEvent"];
	/**
	 * Inspect assistant streaming events before they are emitted to subscribers.
	 * Use this when abort decisions must happen before buffered events continue flowing.
	 */
	onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
	/** Called for non-content tool-choice incapability stream events. */
	onToolChoiceIncapability?: AgentLoopConfig["onToolChoiceIncapability"];

	/**
	 * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
	 */
	onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
	/**
	 * Custom token budgets for thinking levels (token-based providers only).
	 */
	thinkingBudgets?: ThinkingBudgets;

	/**
	 * Sampling temperature for LLM calls. `undefined` uses provider default.
	 */
	temperature?: number;

	/** Additional sampling controls for providers that support them. */
	topP?: number;
	topK?: number;
	minP?: number;
	presencePenalty?: number;
	repetitionPenalty?: number;
	serviceTier?: ServiceTier;
	/**
	 * If true, request that the underlying provider omit reasoning/thinking summaries
	 * from the response. The model still reasons internally; only the human-readable
	 * summary stream is suppressed. Useful when the UI hides thinking blocks anyway.
	 */
	hideThinkingSummary?: boolean;

	/**
	 * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
	 * If the server's requested delay exceeds this value, the request fails immediately,
	 * allowing higher-level retry logic to handle it with user visibility.
	 * Default: 60000 (60 seconds). Set to 0 to disable the cap.
	 */
	maxRetryDelayMs?: number;
	/** Provider request retry budget. Counts retries, not the initial attempt. */
	requestMaxRetries?: number;
	/** Provider stream replay retry budget. Counts retries, not the initial attempt. */
	streamMaxRetries?: number;

	/**
	 * Provides tool execution context, resolved per tool call.
	 * Use for late-bound UI or session state access.
	 */
	getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;

	/**
	 * Optional transform applied to tool call arguments before execution.
	 * Use for deobfuscating secrets or rewriting arguments.
	 */
	transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;

	/** Enable intent tracing schema injection/stripping in the harness. */
	intentTracing?: boolean;
	/** Dynamic tool choice override, resolved per LLM call. */
	getToolChoice?: () => ToolChoice | undefined;

	/**
	 * Cursor exec handlers for local tool execution.
	 */
	cursorExecHandlers?: CursorExecHandlers;

	/**
	 * Cursor tool result callback for exec tool responses.
	 */
	cursorOnToolResult?: CursorToolResultHandler;

	/**
	 * Called after a tool call has been validated and is about to execute.
	 * See {@link AgentLoopConfig.beforeToolCall} for full semantics.
	 */
	beforeToolCall?: AgentLoopConfig["beforeToolCall"];

	/**
	 * Called after a tool finishes executing, before `tool_execution_end` and the tool-result
	 * message are emitted. See {@link AgentLoopConfig.afterToolCall} for full semantics.
	 */
	afterToolCall?: AgentLoopConfig["afterToolCall"];

	/**
	 * Opt-in OpenTelemetry instrumentation. Passing `{}` enables the loop's
	 * GenAI-semantic-convention spans using the global tracer provider. See
	 * {@link AgentLoopConfig.telemetry} for the full surface.
	 */
	telemetry?: AgentLoopConfig["telemetry"];
	/**
	 * Immutable context mode — stabilizes system prompt + tool spec bytes
	 * across turns so DeepSeek/Anthropic prefix caches hit at maximum rate.
	 */
	appendOnlyContext?: AppendOnlyContextManager;
}

export interface AgentPromptOptions {
	toolChoice?: ToolChoice;
	/** Disable transport replay; fallback accounting is owned by the caller. */
	fallbackManaged?: boolean;
	/** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
	onRunAccepted?: () => void;
	/** Called once immediately before every managed upstream request. */
	nextFallbackAttempt?: AgentLoopConfig["nextFallbackAttempt"];
	/** Called after a managed upstream request is accepted and committed. */
	onManagedAttemptAccepted?: AgentLoopConfig["onManagedAttemptAccepted"];
	/** Receives a discarded managed attempt without exposing assistant lifecycle events. */
	onManagedAttemptOutcome?: AgentLoopConfig["onManagedAttemptOutcome"];
}

/** Buffered Cursor tool result with text position at time of call */
interface CursorToolResultEntry {
	toolResult: ToolResultMessage;
	textLengthAtCall: number;
}

export type AgentQueueSnapshot = {
	steering: AgentMessage[];
	followUp: AgentMessage[];
};

export class Agent {
	#state: AgentState = {
		systemPrompt: [],
		model: getBundledModel("google", "gemini-2.5-flash-lite-preview-06-17"),
		thinkingLevel: undefined,
		tools: [],
		messages: [],
		isStreaming: false,
		streamMessage: null,
		pendingToolCalls: new Set<string>(),
		error: undefined,
	};
	#contextRevision = 0;

	#listeners = new Set<(e: AgentEvent) => void>();
	#abortController?: AbortController;
	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
	#transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
	#steeringQueue: AgentMessage[] = [];
	#followUpQueue: AgentMessage[] = [];
	#followUpForceOneAtATime = new WeakSet<AgentMessage>();
	#steeringMode: "all" | "one-at-a-time";
	#followUpMode: "all" | "one-at-a-time";
	#interruptMode: "immediate" | "wait";
	#sessionId?: string;
	#providerSessionId?: string;
	#metadata?: Record<string, unknown>;
	#metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
	#providerSessionState?: Map<string, ProviderSessionState>;
	#thinkingBudgets?: ThinkingBudgets;
	#temperature?: number;
	#topP?: number;
	#topK?: number;
	#minP?: number;
	#presencePenalty?: number;
	#repetitionPenalty?: number;
	#serviceTier?: ServiceTier;
	#hideThinkingSummary?: boolean;
	#maxRetryDelayMs?: number;
	#requestMaxRetries?: number;
	#streamMaxRetries?: number;
	#getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;
	#cursorExecHandlers?: CursorExecHandlers;
	#cursorOnToolResult?: CursorToolResultHandler;
	#runningPrompt?: Promise<void>;
	#resolveRunningPrompt?: () => void;
	#runSequence = 0;
	#activeRunId?: number;
	#continuationGeneration = 0;
	#activeFallbackManaged = false;
	#kimiApiFormat?: "openai" | "anthropic";
	#preferWebsockets?: boolean;
	#transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
	#intentTracing: boolean;
	#getToolChoice?: () => ToolChoice | undefined;
	#onPayload?: SimpleStreamOptions["onPayload"];
	#onResponse?: SimpleStreamOptions["onResponse"];
	#onSseEvent?: SimpleStreamOptions["onSseEvent"];
	#onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
	#onToolChoiceIncapability?: AgentLoopConfig["onToolChoiceIncapability"];
	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
	#onBeforeYield?: () => Promise<void> | void;
	#shouldPause?: AgentLoopConfig["shouldPause"];
	#maintainContext?: AgentLoopConfig["maintainContext"];
	#telemetry?: AgentLoopConfig["telemetry"];
	#appendOnlyContext?: AppendOnlyContextManager;

	get intentTracing(): boolean {
		return this.#intentTracing;
	}

	/** Buffered Cursor tool results with text length at time of call (for correct ordering) */
	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
	#terminalizedLogicalRunIds = new Set<ManagedLogicalRunId>();
	#managedLogicalRunOwner?: ManagedLogicalRunId;

	streamFn: StreamFn;
	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
	getAuthCredentialType?: (provider: string) => "api_key" | "oauth" | undefined;
	/**
	 * Hook invoked after tool arguments are validated and before execution.
	 * Reassign at any time to swap the implementation (e.g. on extension reload).
	 */
	beforeToolCall?: AgentLoopConfig["beforeToolCall"];
	/**
	 * Hook invoked after tool execution and before `tool_execution_end` / tool-result
	 * message emission. Reassign at any time to swap the implementation.
	 */
	afterToolCall?: AgentLoopConfig["afterToolCall"];

	constructor(opts: AgentOptions = {}) {
		this.#state = { ...this.#state, ...opts.initialState };
		this.#convertToLlm = opts.convertToLlm || defaultConvertToLlm;
		this.#transformContext = opts.transformContext;
		this.#steeringMode = opts.steeringMode || "one-at-a-time";
		this.#followUpMode = opts.followUpMode || "one-at-a-time";
		this.#interruptMode = opts.interruptMode || "immediate";
		this.streamFn = opts.streamFn || streamSimple;
		this.#sessionId = opts.sessionId;
		this.#providerSessionId = opts.providerSessionId;
		this.#providerSessionState = opts.providerSessionState;
		this.#thinkingBudgets = opts.thinkingBudgets;
		this.#temperature = opts.temperature;
		this.#topP = opts.topP;
		this.#topK = opts.topK;
		this.#minP = opts.minP;
		this.#presencePenalty = opts.presencePenalty;
		this.#repetitionPenalty = opts.repetitionPenalty;
		this.#serviceTier = opts.serviceTier;
		this.#hideThinkingSummary = opts.hideThinkingSummary;
		this.#maxRetryDelayMs = opts.maxRetryDelayMs;
		this.#requestMaxRetries = opts.requestMaxRetries;
		this.#streamMaxRetries = opts.streamMaxRetries;
		this.getApiKey = opts.getApiKey;
		this.getAuthCredentialType = opts.getAuthCredentialType;
		this.#onPayload = opts.onPayload;
		this.#onResponse = opts.onResponse;
		this.#onSseEvent = opts.onSseEvent;
		this.#getToolContext = opts.getToolContext;
		this.#cursorExecHandlers = opts.cursorExecHandlers;
		this.#cursorOnToolResult = opts.cursorOnToolResult;
		this.#kimiApiFormat = opts.kimiApiFormat;
		this.#preferWebsockets = opts.preferWebsockets;
		this.#transformToolCallArguments = opts.transformToolCallArguments;
		this.#intentTracing = opts.intentTracing === true;
		this.#getToolChoice = opts.getToolChoice;
		this.#onAssistantMessageEvent = opts.onAssistantMessageEvent;
		this.#onToolChoiceIncapability = opts.onToolChoiceIncapability;
		this.#onHarmonyLeak = opts.onHarmonyLeak;
		this.#shouldPause = opts.shouldPause;
		this.beforeToolCall = opts.beforeToolCall;
		this.afterToolCall = opts.afterToolCall;
		this.#telemetry = opts.telemetry;
		this.#appendOnlyContext = opts.appendOnlyContext;
	}

	/**
	 * Get the current session ID used for provider caching.
	 */
	get sessionId(): string | undefined {
		return this.#sessionId;
	}

	/**
	 * Set the session ID for provider caching.
	 * Call this when switching sessions (new session, branch, resume).
	 */
	set sessionId(value: string | undefined) {
		this.#sessionId = value;
	}

	get providerSessionId(): string | undefined {
		return this.#providerSessionId;
	}

	set providerSessionId(value: string | undefined) {
		this.#providerSessionId = value;
	}

	/**
	 * Whether websocket transport is preferred when the provider implementation
	 * supports it. Read by maintenance one-shot calls (compaction, handoff,
	 * branch summary) so they forward the same transport preference as live turns.
	 */
	get preferWebsockets(): boolean | undefined {
		return this.#preferWebsockets;
	}

	/**
	 * Static metadata forwarded to every API request when no resolver is installed
	 * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this
	 * clears any installed resolver.
	 *
	 * For live/provider-aware metadata (e.g. Anthropic OAuth `account_uuid` that
	 * must reflect the credential selected per-request), use
	 * {@link setMetadataResolver} and read via {@link metadataForProvider}.
	 */
	get metadata(): Record<string, unknown> | undefined {
		return this.#metadata;
	}

	set metadata(value: Record<string, unknown> | undefined) {
		this.#metadata = value;
		this.#metadataResolver = undefined;
	}

	/**
	 * Resolve request metadata for the given provider at call time. When a
	 * resolver is installed via {@link setMetadataResolver}, it is invoked with
	 * the provider string so the result can be scoped (e.g. `account_uuid` is
	 * only included for `"anthropic"` requests). Falls back to the static
	 * {@link metadata} value when no resolver is set.
	 */
	metadataForProvider(provider: string): Record<string, unknown> | undefined {
		if (this.#metadataResolver) return this.#metadataResolver(provider);
		return this.#metadata;
	}

	/**
	 * Install a function that resolves request metadata at call time. The
	 * resolver receives the target provider string and can gate provider-specific
	 * fields (e.g. `account_uuid` only for `"anthropic"`). Invoked per LLM
	 * request by `agent-loop` after `getApiKey` selects the session-sticky
	 * credential. Pass `undefined` to clear and revert to the static
	 * {@link metadata} value.
	 */
	setMetadataResolver(resolver: ((provider: string) => Record<string, unknown> | undefined) | undefined): void {
		this.#metadataResolver = resolver;
	}

	/**
	 * Read the active OpenTelemetry configuration. Returns `undefined` when
	 * instrumentation is disabled. Callers spawning child runs (e.g. subagent
	 * dispatch) forward this to the child's loop so its spans appear under the
	 * parent's active context with the subagent's own identity stamped.
	 */
	get telemetry(): AgentLoopConfig["telemetry"] | undefined {
		return this.#telemetry;
	}

	/**
	 * Replace the active OpenTelemetry configuration. Pass `undefined` to
	 * disable instrumentation. Applies to the *next* `agentLoop` invocation —
	 * in-flight loops keep the configuration they started with.
	 */
	setTelemetry(telemetry: AgentLoopConfig["telemetry"] | undefined): void {
		this.#telemetry = telemetry;
	}

	/**
	 * Get provider-scoped mutable session state store.
	 */
	get providerSessionState(): Map<string, ProviderSessionState> | undefined {
		return this.#providerSessionState;
	}

	/**
	 * Set provider-scoped mutable session state store.
	 */
	set providerSessionState(value: Map<string, ProviderSessionState> | undefined) {
		this.#providerSessionState = value;
	}

	/**
	 * Get the current thinking budgets.
	 */
	get thinkingBudgets(): ThinkingBudgets | undefined {
		return this.#thinkingBudgets;
	}

	/**
	 * Set custom thinking budgets for token-based providers.
	 */
	set thinkingBudgets(value: ThinkingBudgets | undefined) {
		this.#thinkingBudgets = value;
	}

	/**
	 * Get the current sampling temperature.
	 */
	get temperature(): number | undefined {
		return this.#temperature;
	}

	/**
	 * Set sampling temperature for LLM calls. `undefined` uses provider default.
	 */
	set temperature(value: number | undefined) {
		this.#temperature = value;
	}

	get topP(): number | undefined {
		return this.#topP;
	}

	set topP(value: number | undefined) {
		this.#topP = value;
	}

	get topK(): number | undefined {
		return this.#topK;
	}

	set topK(value: number | undefined) {
		this.#topK = value;
	}

	get minP(): number | undefined {
		return this.#minP;
	}

	set minP(value: number | undefined) {
		this.#minP = value;
	}

	get presencePenalty(): number | undefined {
		return this.#presencePenalty;
	}

	set presencePenalty(value: number | undefined) {
		this.#presencePenalty = value;
	}

	get repetitionPenalty(): number | undefined {
		return this.#repetitionPenalty;
	}

	set repetitionPenalty(value: number | undefined) {
		this.#repetitionPenalty = value;
	}

	get serviceTier(): ServiceTier | undefined {
		return this.#serviceTier;
	}

	set serviceTier(value: ServiceTier | undefined) {
		this.#serviceTier = value;
	}

	get hideThinkingSummary(): boolean | undefined {
		return this.#hideThinkingSummary;
	}

	set hideThinkingSummary(value: boolean | undefined) {
		this.#hideThinkingSummary = value;
	}

	/**
	 * Get the current max retry delay in milliseconds.
	 */
	get maxRetryDelayMs(): number | undefined {
		return this.#maxRetryDelayMs;
	}

	/**
	 * Set the maximum delay to wait for server-requested retries.
	 * Set to 0 to disable the cap.
	 */
	set maxRetryDelayMs(value: number | undefined) {
		this.#maxRetryDelayMs = value;
	}

	get requestMaxRetries(): number | undefined {
		return this.#requestMaxRetries;
	}

	set requestMaxRetries(value: number | undefined) {
		this.#requestMaxRetries = value;
	}

	get streamMaxRetries(): number | undefined {
		return this.#streamMaxRetries;
	}

	set streamMaxRetries(value: number | undefined) {
		this.#streamMaxRetries = value;
	}

	get state(): AgentState {
		return this.#state;
	}

	get contextRevision(): number {
		return this.#contextRevision;
	}

	get appendOnlyContext(): AppendOnlyContextManager | undefined {
		return this.#appendOnlyContext;
	}

	setAppendOnlyContext(manager?: AppendOnlyContextManager): void {
		this.#appendOnlyContext = manager;
	}

	subscribe(fn: (e: AgentEvent) => void): () => void {
		this.#listeners.add(fn);
		return () => this.#listeners.delete(fn);
	}

	setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void {
		this.#onResponse = fn;
	}

	setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void {
		this.#onSseEvent = fn;
	}

	setAssistantMessageEventInterceptor(
		fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined,
	): void {
		this.#onAssistantMessageEvent = fn;
	}

	setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void {
		this.#onBeforeYield = fn;
	}

	setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void {
		this.#shouldPause = fn;
	}

	setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void {
		this.#maintainContext = fn;
	}

	emitExternalEvent(event: AgentEvent) {
		switch (event.type) {
			case "message_start":
			case "message_update":
				this.#state.streamMessage = event.message;
				break;
			case "message_end":
				this.#state.streamMessage = null;
				this.appendMessage(event.message);
				break;
			case "tool_execution_start": {
				const pending = new Set(this.#state.pendingToolCalls);
				pending.add(event.toolCallId);
				this.#state.pendingToolCalls = pending;
				break;
			}
			case "tool_execution_end": {
				const pending = new Set(this.#state.pendingToolCalls);
				pending.delete(event.toolCallId);
				this.#state.pendingToolCalls = pending;
				break;
			}
		}

		this.#emit(event);
	}

	createExternalEventEmitterForCurrentRun(): ((event: AgentEvent) => void) | undefined {
		const runId = this.#activeRunId;
		if (runId === undefined) return undefined;
		return (event: AgentEvent) => {
			if (this.#activeRunId !== runId) return;
			this.emitExternalEvent(event);
		};
	}

	#assertActiveRun(runId: number): void {
		if (this.#activeRunId !== runId) {
			throw new Error("Ignoring Cursor exec callback from an inactive agent run.");
		}
	}

	#cursorExecHandlersForRun(runId: number): CursorExecHandlers | undefined {
		const source = this.#cursorExecHandlers;
		if (!source) return undefined;

		const guarded: CursorExecHandlers = {};
		// Bind each handler to `source`: they are methods of a CursorExecHandlers
		// instance that reference private fields via `this`. Extracting them bare
		// (`const read = source.read`) and calling `read(args)` would invoke them with
		// `this === undefined`, throwing "undefined is not an object (this.#optionsForCall)".
		const read = source.read?.bind(source);
		if (read) {
			guarded.read = async args => {
				this.#assertActiveRun(runId);
				const result = await read(args);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const ls = source.ls?.bind(source);
		if (ls) {
			guarded.ls = async args => {
				this.#assertActiveRun(runId);
				const result = await ls(args);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const grep = source.grep?.bind(source);
		if (grep) {
			guarded.grep = async args => {
				this.#assertActiveRun(runId);
				const result = await grep(args);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const write = source.write?.bind(source);
		if (write) {
			guarded.write = async args => {
				this.#assertActiveRun(runId);
				const result = await write(args);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const deleteHandler = source.delete?.bind(source);
		if (deleteHandler) {
			guarded.delete = async args => {
				this.#assertActiveRun(runId);
				const result = await deleteHandler(args);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const shell = source.shell?.bind(source);
		if (shell) {
			guarded.shell = async args => {
				this.#assertActiveRun(runId);
				const result = await shell(args);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const shellStream = source.shellStream?.bind(source);
		if (shellStream) {
			guarded.shellStream = async (args, callbacks) => {
				this.#assertActiveRun(runId);
				const result = await shellStream(args, callbacks);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const diagnostics = source.diagnostics?.bind(source);
		if (diagnostics) {
			guarded.diagnostics = async args => {
				this.#assertActiveRun(runId);
				const result = await diagnostics(args);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const mcp = source.mcp?.bind(source);
		if (mcp) {
			guarded.mcp = async call => {
				this.#assertActiveRun(runId);
				const result = await mcp(call);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		const onToolResult = source.onToolResult;
		if (onToolResult) {
			guarded.onToolResult = async message => {
				this.#assertActiveRun(runId);
				const result = await onToolResult(message);
				this.#assertActiveRun(runId);
				return result;
			};
		}
		return guarded;
	}

	// State mutators
	setSystemPrompt(v: string[]) {
		this.#state.systemPrompt = v;
		this.#contextRevision++;
	}

	setModel(m: Model | undefined) {
		this.#state.model = m;
		this.#contextRevision++;
	}

	setThinkingLevel(l: Effort | undefined) {
		this.#state.thinkingLevel = l;
	}

	setSteeringMode(mode: "all" | "one-at-a-time") {
		this.#steeringMode = mode;
	}

	getSteeringMode(): "all" | "one-at-a-time" {
		return this.#steeringMode;
	}

	setFollowUpMode(mode: "all" | "one-at-a-time") {
		this.#followUpMode = mode;
	}

	getFollowUpMode(): "all" | "one-at-a-time" {
		return this.#followUpMode;
	}

	setInterruptMode(mode: "immediate" | "wait") {
		this.#interruptMode = mode;
	}

	getInterruptMode(): "immediate" | "wait" {
		return this.#interruptMode;
	}

	setTools(t: AgentTool<any>[]) {
		this.#state.tools = t;
		this.#contextRevision++;
	}

	replaceMessages(ms: AgentMessage[]) {
		this.#state.messages = ms.slice();
		this.#contextRevision++;
	}

	appendMessage(m: AgentMessage) {
		// In-place push (not [...messages, m]): appending M messages over a session of
		// N is O(N+M), not O(M*N). Consumers read state.messages fresh; run() snapshots
		// via slice() at the API boundary, so no caller relies on per-append array identity.
		this.#state.messages.push(m);
		this.#contextRevision++;
	}

	popMessage(): AgentMessage | undefined {
		const messages = this.#state.messages.slice(0, -1);
		const removed = this.#state.messages.at(-1);
		this.#state.messages = messages;
		this.#contextRevision++;

		if (removed && this.#state.streamMessage === removed) {
			this.#state.streamMessage = null;
		}

		return removed;
	}

	/**
	 * For callers that mutate committed messages or the system prompt in place
	 * outside Agent-owned mutators.
	 */
	touchContext(): void {
		this.#contextRevision++;
	}

	/**
	 * Queue a steering message to interrupt the agent mid-run.
	 * Delivered after current tool execution, skips remaining tools.
	 */
	steer(m: AgentMessage) {
		assertUserImagePlaceholdersHavePayload([m]);
		this.#steeringQueue.push(m);
	}

	/**
	 * Queue a follow-up message to be processed after the agent finishes.
	 * Delivered only when agent has no more tool calls or steering messages.
	 *
	 * `forceOneAtATime` lets UI composer queues preserve prompt-by-prompt
	 * delivery even when the session-wide follow-up mode is set to `all` for
	 * other integration paths.
	 */
	followUp(m: AgentMessage, options?: { forceOneAtATime?: boolean }) {
		assertUserImagePlaceholdersHavePayload([m]);
		if (options?.forceOneAtATime) {
			this.#followUpForceOneAtATime.add(m);
		}
		this.#followUpQueue.push(m);
	}

	clearSteeringQueue() {
		this.#steeringQueue = [];
	}

	clearFollowUpQueue() {
		this.#followUpQueue = [];
	}

	clearAllQueues() {
		this.#steeringQueue = [];
		this.#followUpQueue = [];
	}

	hasQueuedMessages(): boolean {
		return this.#steeringQueue.length > 0 || this.#followUpQueue.length > 0;
	}

	hasQueuedSteering(): boolean {
		return this.#steeringQueue.length > 0;
	}

	/**
	 * Snapshot the steering queue without mutating it. Used to preserve queued
	 * steering across maintenance ops (compaction/handoff) that call reset().
	 */
	snapshotSteering(): AgentMessage[] {
		return this.#steeringQueue.slice();
	}

	/**
	 * Restore previously snapshotted steering messages ahead of any newly
	 * queued ones. No-op for an empty snapshot.
	 */
	restoreSteering(messages: AgentMessage[]): void {
		if (messages.length === 0) return;
		this.#steeringQueue = [...messages, ...this.#steeringQueue];
	}

	/** Snapshot the follow-up queue without mutating it. */
	snapshotFollowUp(): AgentMessage[] {
		return this.#followUpQueue.slice();
	}

	/** Restore previously snapshotted follow-up messages ahead of any newly queued ones. */
	restoreFollowUp(messages: AgentMessage[]): void {
		if (messages.length === 0) return;
		this.#followUpQueue = [...messages, ...this.#followUpQueue];
	}

	/** Snapshot both executable queues as one atomic session-level view. */
	snapshotQueues(): AgentQueueSnapshot {
		return {
			steering: this.#steeringQueue.slice(),
			followUp: this.#followUpQueue.slice(),
		};
	}

	/** Replace both executable queues with a prior snapshot. */
	restoreQueues(snapshot: AgentQueueSnapshot): void {
		this.#steeringQueue = snapshot.steering.slice();
		this.#followUpQueue = snapshot.followUp.slice();
	}

	#dequeueSteeringMessages(): AgentMessage[] {
		if (this.#steeringMode === "one-at-a-time") {
			if (this.#steeringQueue.length > 0) {
				const first = this.#steeringQueue[0];
				this.#steeringQueue = this.#steeringQueue.slice(1);
				return [first];
			}
			return [];
		}
		const steering = this.#steeringQueue.slice();
		this.#steeringQueue = [];
		return steering;
	}

	#dequeueFollowUpMessages(): AgentMessage[] {
		if (this.#followUpMode === "one-at-a-time") {
			if (this.#followUpQueue.length > 0) {
				const first = this.#followUpQueue[0];
				this.#followUpQueue = this.#followUpQueue.slice(1);
				return [first];
			}
			return [];
		}

		const first = this.#followUpQueue[0];
		if (!first) return [];
		if (this.#followUpForceOneAtATime.has(first)) {
			this.#followUpQueue = this.#followUpQueue.slice(1);
			return [first];
		}

		const forcedIndex = this.#followUpQueue.findIndex(message => this.#followUpForceOneAtATime.has(message));
		const takeCount = forcedIndex === -1 ? this.#followUpQueue.length : forcedIndex;
		const followUp = this.#followUpQueue.slice(0, takeCount);
		this.#followUpQueue = this.#followUpQueue.slice(takeCount);
		return followUp;
	}

	/**
	 * Remove and return the last steering message from the queue (LIFO).
	 * Used by dequeue keybinding.
	 */
	popLastSteer(): AgentMessage | undefined {
		return this.#steeringQueue.pop();
	}
	removeSteerAt(index: number): AgentMessage | undefined {
		if (index < 0 || index >= this.#steeringQueue.length) return undefined;
		const [removed] = this.#steeringQueue.splice(index, 1);
		return removed;
	}

	moveSteer(fromIndex: number, toIndex: number): boolean {
		return this.#moveQueuedMessage(this.#steeringQueue, fromIndex, toIndex);
	}

	/**
	 * Remove and return the last follow-up message from the queue (LIFO).
	 * Used by dequeue keybinding.
	 */
	popLastFollowUp(): AgentMessage | undefined {
		return this.#followUpQueue.pop();
	}
	removeFollowUpAt(index: number): AgentMessage | undefined {
		if (index < 0 || index >= this.#followUpQueue.length) return undefined;
		const [removed] = this.#followUpQueue.splice(index, 1);
		return removed;
	}

	moveFollowUp(fromIndex: number, toIndex: number): boolean {
		return this.#moveQueuedMessage(this.#followUpQueue, fromIndex, toIndex);
	}

	#moveQueuedMessage<T>(queue: T[], fromIndex: number, toIndex: number): boolean {
		if (fromIndex < 0 || fromIndex >= queue.length) return false;
		if (toIndex < 0 || toIndex >= queue.length) return false;
		if (fromIndex === toIndex) return true;
		const [item] = queue.splice(fromIndex, 1);
		if (item === undefined) return false;
		queue.splice(toIndex, 0, item);
		return true;
	}

	/** Remove queued steering+follow-up messages matching `predicate`, preserving order of the rest. */
	removeQueuedMessages(predicate: (message: AgentMessage) => boolean): {
		steering: number;
		followUp: number;
		total: number;
	} {
		const beforeSteering = this.#steeringQueue.length;
		const beforeFollowUp = this.#followUpQueue.length;
		this.#steeringQueue = this.#steeringQueue.filter(m => !predicate(m));
		this.#followUpQueue = this.#followUpQueue.filter(m => !predicate(m));
		const steering = beforeSteering - this.#steeringQueue.length;
		const followUp = beforeFollowUp - this.#followUpQueue.length;
		return { steering, followUp, total: steering + followUp };
	}

	clearMessages() {
		this.#state.messages = [];
		this.#contextRevision++;
	}

	abort() {
		this.#abortController?.abort();
	}

	/**
	 * Force the current run out of the busy/streaming state when cooperative abort
	 * did not drain. The abandoned provider/tool stream may still settle later, so
	 * #runLoop guards every state mutation with a run id.
	 */
	forceAbort(reason = "Force aborted"): boolean {
		const runId = this.#activeRunId;
		const managedLogicalRunId = this.#managedLogicalRunOwner;
		const hadActiveRun = runId !== undefined && (this.#runningPrompt !== undefined || this.#state.isStreaming);
		if (!hadActiveRun) return false;

		this.#abortController?.abort(reason);
		this.#continuationGeneration++;
		this.#state.isStreaming = false;
		this.#state.streamMessage = null;
		this.#state.pendingToolCalls = new Set<string>();
		this.#abortController = undefined;
		this.#cursorToolResultBuffer = [];
		this.#managedLogicalRunOwner = undefined;

		const resolve = this.#resolveRunningPrompt;
		this.#runningPrompt = undefined;
		this.#resolveRunningPrompt = undefined;
		this.#activeRunId = undefined;
		resolve?.();
		if (this.#activeFallbackManaged) {
			this.requestRunTerminal(managedLogicalRunId ?? runId, { stopReason: "cancelled" });
		} else {
			this.#finalizeRun(runId, { type: "agent_end", messages: [] });
		}
		return true;
	}

	waitForIdle(): Promise<void> {
		return this.#runningPrompt ?? Promise.resolve();
	}

	/** The active per-attempt run identifier. */
	get activeRunId(): number | undefined {
		return this.#activeRunId;
	}

	/**
	 * Stable identifier for the active managed logical run, shared by every retry
	 * attempt. Pass this value to requestRunTerminal(); never retain activeRunId
	 * for managed terminal completion.
	 */
	get currentManagedLogicalRunId(): ManagedLogicalRunId | undefined {
		return this.#managedLogicalRunOwner;
	}

	/**
	 * Request terminal completion through the single logical-run keyed finalizer.
	 *
	 * For managed runs, logicalRunId must be currentManagedLogicalRunId from any
	 * attempt in the retry chain. Non-managed runs use their activeRunId. Terminal
	 * requests with messages emit a committed message_start/message_end lifecycle
	 * for each diagnostic before agent_end. Requests without messages (such as
	 * cancellation) emit only agent_end.
	 */
	requestRunTerminal(logicalRunId: ManagedLogicalRunId, request: RunTerminalRequest): boolean {
		if (this.#terminalizedLogicalRunIds.has(logicalRunId)) return false;
		if (this.#managedLogicalRunOwner === logicalRunId) {
			this.#managedLogicalRunOwner = undefined;
		}
		this.#finalizeRun(
			logicalRunId,
			{
				type: "agent_end",
				messages: request.messages ?? [],
				...(request.stopReason === "cancelled" ? { stopReason: "cancelled" as const } : {}),
			},
			() => {
				for (const message of request.messages ?? []) {
					this.#emit({ type: "message_start", message });
					this.appendMessage(message);
					this.#emit({ type: "message_end", message });
				}
			},
		);
		return true;
	}

	reset() {
		this.#state.messages = [];
		this.#contextRevision++;
		this.#state.isStreaming = false;
		this.#state.streamMessage = null;
		this.#state.pendingToolCalls = new Set<string>();
		this.#managedLogicalRunOwner = undefined;
		this.#state.error = undefined;
		this.#steeringQueue = [];
		this.#followUpQueue = [];
	}

	/** Send a prompt with an AgentMessage */
	async prompt(message: AgentMessage | AgentMessage[], options?: AgentPromptOptions): Promise<void>;
	async prompt(input: string, options?: AgentPromptOptions): Promise<void>;
	async prompt(input: string, images?: ImageContent[], options?: AgentPromptOptions): Promise<void>;
	async prompt(
		input: string | AgentMessage | AgentMessage[],
		imagesOrOptions?: ImageContent[] | AgentPromptOptions,
		options?: AgentPromptOptions,
	) {
		if (this.#state.isStreaming) {
			throw new AgentBusyError();
		}

		const model = this.#state.model;
		if (!model) throw new Error("No model configured");

		let msgs: AgentMessage[];
		let promptOptions: AgentPromptOptions | undefined;
		let images: ImageContent[] | undefined;

		if (Array.isArray(input)) {
			msgs = input;
			promptOptions = imagesOrOptions as AgentPromptOptions | undefined;
		} else if (typeof input === "string") {
			if (Array.isArray(imagesOrOptions)) {
				images = imagesOrOptions;
				promptOptions = options;
			} else {
				promptOptions = imagesOrOptions;
			}
			const content: Array<TextContent | ImageContent> = [{ type: "text", text: input }];
			if (images && images.length > 0) {
				content.push(...images);
			}
			msgs = [
				{
					role: "user",
					content,
					timestamp: Date.now(),
				},
			];
		} else {
			msgs = [input];
			promptOptions = imagesOrOptions as AgentPromptOptions | undefined;
		}

		assertUserImagePlaceholdersHavePayload(msgs);
		if (this.#managedLogicalRunOwner !== undefined) {
			this.requestRunTerminal(this.#managedLogicalRunOwner, { stopReason: "cancelled" });
			this.#managedLogicalRunOwner = undefined;
		}

		await this.#runLoop(msgs, promptOptions);
	}

	/**
	 * Continue from current context (used for retries and resuming queued messages).
	 */
	async continue(options?: AgentPromptOptions) {
		if (this.#state.isStreaming) {
			throw new AgentBusyError();
		}

		const messages = this.#state.messages;
		if (messages.length === 0) {
			throw new Error("No messages to continue from");
		}
		if (messages[messages.length - 1].role === "assistant") {
			const queuedSteering = this.#dequeueSteeringMessages();
			if (queuedSteering.length > 0) {
				await this.#runLoop(queuedSteering, { ...options, skipInitialSteeringPoll: true });
				return;
			}

			const queuedFollowUp = this.#dequeueFollowUpMessages();
			if (queuedFollowUp.length > 0) {
				await this.#runLoop(queuedFollowUp, options);
				return;
			}

			throw new Error("Cannot continue from message role: assistant");
		}

		if (!canContinuePersistedHistory(messages)) {
			throw new Error("No messages to continue from");
		}

		await this.#runLoop(undefined, options);
	}

	/**
	 * Run the agent loop.
	 * If messages are provided, starts a new conversation turn with those messages.
	 * Otherwise, continues from existing context.
	 */
	async #runLoop(messages?: AgentMessage[], options?: AgentPromptOptions & { skipInitialSteeringPoll?: boolean }) {
		const model = this.#state.model;
		if (!model) throw new Error("No model configured");

		let skipInitialSteeringPoll = options?.skipInitialSteeringPoll === true;

		const { promise, resolve } = Promise.withResolvers<void>();
		this.#runningPrompt = promise;
		this.#resolveRunningPrompt = resolve;

		const runId = ++this.#runSequence;
		const continuationGeneration = ++this.#continuationGeneration;
		this.#activeRunId = runId;
		const abortController = new AbortController();
		this.#abortController = abortController;
		this.#state.isStreaming = true;
		this.#state.streamMessage = null;
		this.#state.error = undefined;
		options?.onRunAccepted?.();

		const fallbackManaged = options?.fallbackManaged === true;
		const managedLogicalRunOwner = fallbackManaged ? (this.#managedLogicalRunOwner ?? runId) : undefined;
		const startsManagedLogicalRun = fallbackManaged && this.#managedLogicalRunOwner === undefined;
		if (startsManagedLogicalRun) {
			this.#managedLogicalRunOwner = managedLogicalRunOwner;
			this.#emit({ type: "agent_start" });
		}
		if (fallbackManaged && this.#cursorToolResultBuffer.length > 0) {
			const error = new ManagedCursorInvariantError(
				"Managed Cursor attempt started with buffered provider-side tool results",
			);
			this.#state.isStreaming = false;
			this.#abortController = undefined;
			this.#activeRunId = undefined;
			this.#runningPrompt = undefined;
			this.#resolveRunningPrompt = undefined;
			resolve();
			this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: "error" });
			this.#managedLogicalRunOwner = undefined;
			throw error;
		}
		// Each run gets a fresh buffer only after managed stale-state validation.
		this.#cursorToolResultBuffer = [];
		this.#activeFallbackManaged = fallbackManaged;

		const reasoning = this.#state.thinkingLevel;
		const context: AgentContext = {
			systemPrompt: this.#state.systemPrompt,
			messages: this.#state.messages.slice(),
			tools: this.#state.tools,
		};

		const cursorOnToolResult =
			!fallbackManaged && (this.#cursorExecHandlers || this.#cursorOnToolResult)
				? async (message: ToolResultMessage) => {
						let finalMessage = message;
						if (this.#activeRunId !== runId) {
							return finalMessage;
						}
						if (this.#cursorOnToolResult) {
							try {
								const updated = await this.#cursorOnToolResult(message);
								if (this.#activeRunId !== runId) {
									return finalMessage;
								}
								if (updated) {
									finalMessage = updated;
								}
							} catch {}
						}
						// Cursor executes tools server-side during streaming, so the assistant message
						// already incorporates results. We buffer here and emit in correct order
						// when the assistant message ends.
						const textLength = this.#getAssistantTextLength(this.#state.streamMessage);
						this.#cursorToolResultBuffer.push({ toolResult: finalMessage, textLengthAtCall: textLength });
						return finalMessage;
					}
				: undefined;

		const getToolChoice = () =>
			this.#getToolChoice?.() ?? refreshToolChoiceForActiveTools(options?.toolChoice, this.#state.tools);
		const cursorExecHandlers = fallbackManaged ? undefined : this.#cursorExecHandlersForRun(runId);
		let managedDecision: ManagedAttemptDecision | undefined;
		let managedOutcome: ManagedAttemptOutcome | undefined;
		let maintenanceInterrupted = false;

		const config: AgentLoopConfig = {
			model,
			reasoning,
			temperature: this.#temperature,
			topP: this.#topP,
			topK: this.#topK,
			minP: this.#minP,
			presencePenalty: this.#presencePenalty,
			repetitionPenalty: this.#repetitionPenalty,
			serviceTier: this.#serviceTier,
			hideThinkingSummary: this.#hideThinkingSummary,
			interruptMode: this.#interruptMode,
			sessionId: this.#sessionId,
			providerSessionId: this.#providerSessionId,
			metadata: this.#metadataResolver ? undefined : this.#metadata,
			metadataResolver: this.#metadataResolver,
			providerSessionState: this.#providerSessionState,
			thinkingBudgets: this.#thinkingBudgets,
			maxRetryDelayMs: this.#maxRetryDelayMs,
			requestMaxRetries: this.#requestMaxRetries,
			streamMaxRetries: this.#streamMaxRetries,
			...(fallbackManaged
				? {
						fallbackManaged: true,
						nextFallbackAttempt: options?.nextFallbackAttempt,
						onManagedAttemptAccepted: options?.onManagedAttemptAccepted,
						onManagedAttemptOutcome: async outcome => {
							managedOutcome = outcome;
							managedDecision = (await options?.onManagedAttemptOutcome?.(outcome)) ?? {
								type: "terminal",
								terminal: { stopReason: outcome.type === "run_terminal" ? outcome.reason : "error" },
							};
							return managedDecision;
						},
					}
				: {}),
			kimiApiFormat: this.#kimiApiFormat,
			preferWebsockets: this.#preferWebsockets,
			convertToLlm: this.#convertToLlm,
			transformContext: this.#transformContext,
			onPayload: this.#onPayload,
			onResponse: this.#onResponse,
			onSseEvent: this.#onSseEvent,
			signal: abortController.signal,
			getApiKey: this.getApiKey,
			getAuthCredentialType: this.getAuthCredentialType,
			getToolContext: this.#getToolContext,
			syncContextBeforeModelCall: async context => {
				if (this.#listeners.size > 0) {
					await Bun.sleep(0);
				}
				context.systemPrompt = this.#state.systemPrompt;
				context.tools = this.#state.tools;
			},
			...(cursorExecHandlers ? { cursorExecHandlers } : {}),
			...(cursorOnToolResult ? { cursorOnToolResult } : {}),
			transformToolCallArguments: this.#transformToolCallArguments,
			intentTracing: this.#intentTracing,
			appendOnlyContext: this.#appendOnlyContext,
			beforeToolCall: this.beforeToolCall
				? async (ctx, signal) => {
						if (this.#activeRunId !== runId) return undefined;
						const result = await this.beforeToolCall?.(ctx, signal);
						if (this.#activeRunId !== runId) return undefined;
						return result;
					}
				: undefined,
			afterToolCall: this.afterToolCall
				? async (ctx, signal) => {
						if (this.#activeRunId !== runId) return undefined;
						const result = await this.afterToolCall?.(ctx, signal);
						if (this.#activeRunId !== runId) return undefined;
						return result;
					}
				: undefined,
			onAssistantMessageEvent: this.#onAssistantMessageEvent
				? (message, event) => {
						if (this.#activeRunId !== runId) return;
						this.#onAssistantMessageEvent?.(message, event);
					}
				: undefined,
			onToolChoiceIncapability: this.#onToolChoiceIncapability
				? event => {
						if (this.#activeRunId !== runId) return;
						this.#onToolChoiceIncapability?.(event);
					}
				: undefined,
			onHarmonyLeak: this.#onHarmonyLeak,
			getToolChoice,
			getReasoning: () => this.#state.thinkingLevel,
			getSteeringMessages: async () => {
				if (this.#activeRunId !== runId) {
					return [];
				}
				if (skipInitialSteeringPoll) {
					skipInitialSteeringPoll = false;
					return [];
				}
				const queued = this.#dequeueSteeringMessages();
				if (this.#activeRunId !== runId) {
					this.#steeringQueue = [...queued, ...this.#steeringQueue];
					return [];
				}
				return queued;
			},
			getFollowUpMessages: async () => {
				if (this.#activeRunId !== runId) {
					return [];
				}
				const queued = this.#dequeueFollowUpMessages();
				if (this.#activeRunId !== runId) {
					this.#followUpQueue = [...queued, ...this.#followUpQueue];
					return [];
				}
				return queued;
			},
			onBeforeYield: async () => {
				if (this.#activeRunId !== runId) return;
				await this.#onBeforeYield?.();
			},
			shouldPause: () => {
				if (this.#activeRunId !== runId) return false;
				return this.#shouldPause?.() === true;
			},
			maintainContext: this.#maintainContext
				? async (context, lifecycle) => {
						if (this.#activeRunId !== runId) return "not-needed";
						return (await this.#maintainContext?.(context, lifecycle)) ?? "not-needed";
					}
				: undefined,
			telemetry: this.#telemetry,
		};

		let partial: AgentMessage | null = null;

		try {
			const stream = messages
				? agentLoop(messages, context, config, abortController.signal, this.streamFn, !fallbackManaged)
				: agentLoopContinue(context, config, abortController.signal, this.streamFn, !fallbackManaged);

			for await (const event of stream) {
				if (this.#activeRunId !== runId) {
					break;
				}

				// Update internal state based on events
				switch (event.type) {
					case "message_start":
						partial = event.message;
						this.#state.streamMessage = event.message;
						break;

					case "message_update":
						partial = event.message;
						this.#state.streamMessage = event.message;
						break;

					case "message_end":
						if (fallbackManaged && this.#cursorToolResultBuffer.length > 0) {
							throw new ManagedCursorInvariantError();
						}
						partial = null;
						// Check if this is an assistant message with buffered Cursor tool results.
						// If so, split the message to emit tool results at the correct position.
						if (event.message.role === "assistant" && this.#cursorToolResultBuffer.length > 0) {
							this.#emitCursorSplitAssistantMessage(event.message as AssistantMessage);
							continue; // Skip default emit - split method handles everything
						}
						this.#state.streamMessage = null;
						this.appendMessage(event.message);
						break;

					case "tool_execution_start": {
						const s = new Set(this.#state.pendingToolCalls);
						s.add(event.toolCallId);
						this.#state.pendingToolCalls = s;
						break;
					}

					case "tool_execution_end": {
						const s = new Set(this.#state.pendingToolCalls);
						s.delete(event.toolCallId);
						this.#state.pendingToolCalls = s;
						break;
					}

					case "turn_end":
						if (event.message.role === "assistant" && (event.message as any).errorMessage) {
							this.#state.error = (event.message as any).errorMessage;
						}
						break;

					case "agent_end":
						if (fallbackManaged && managedOutcome) {
							continue;
						}
						this.#state.isStreaming = false;
						this.#state.streamMessage = null;
						if (event.stopReason === "maintenance") {
							maintenanceInterrupted = true;
							this.#emit(event);
							continue;
						}
						this.#finalizeRun(managedLogicalRunOwner ?? runId, event);
						continue;
				}

				// Emit to listeners
				this.#emit(event);
			}

			if (this.#activeRunId !== runId) {
				return;
			}
			if (managedOutcome) {
				if (managedDecision?.type === "terminal") {
					this.requestRunTerminal(managedLogicalRunOwner ?? runId, managedDecision.terminal);
				} else if (managedOutcome.type === "run_terminal") {
					this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: managedOutcome.reason });
				} else if (managedDecision?.type !== "retry" && managedDecision?.type !== "maintenance") {
					this.#finalizeRun(managedLogicalRunOwner ?? runId);
				}
			}

			// Handle any remaining partial message
			if (partial && partial.role === "assistant" && Array.isArray(partial.content) && partial.content.length > 0) {
				const onlyEmpty = !partial.content.some(
					c =>
						(c.type === "thinking" && c.thinking.trim().length > 0) ||
						(c.type === "text" && c.text.trim().length > 0) ||
						(c.type === "toolCall" && c.name.trim().length > 0),
				);
				if (!onlyEmpty) {
					this.appendMessage(partial);
				} else {
					if (abortController.signal.aborted) {
						throw new Error("Request was aborted");
					}
				}
			}
		} catch (err: any) {
			if (this.#activeRunId !== runId) {
				return;
			}

			const errorMsg: AgentMessage = {
				role: "assistant",
				content: [{ type: "text", text: "" }],
				api: model.api,
				provider: model.provider,
				model: model.id,
				usage: {
					input: 0,
					output: 0,
					cacheRead: 0,
					cacheWrite: 0,
					totalTokens: 0,
					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
				},
				stopReason: abortController.signal.aborted ? "aborted" : "error",
				errorMessage: err?.message || String(err),
				errorStatus: extractHttpStatusFromError({ status: err?.errorStatus }) ?? extractHttpStatusFromError(err),
				timestamp: Date.now(),
			} as AgentMessage;

			this.#state.error = err?.message || String(err);
			this.requestRunTerminal(managedLogicalRunOwner ?? runId, {
				stopReason: abortController.signal.aborted ? "cancelled" : "error",
				messages: [errorMsg],
			});
		} finally {
			let continuation: ManagedAttemptContinuation | undefined;
			if (
				managedOutcome?.type !== "run_terminal" &&
				(managedDecision?.type === "retry" || managedDecision?.type === "maintenance")
			) {
				continuation = managedDecision.continuation;
			}
			const ownership: ManagedAttemptContinuationOwnership = {
				runId,
				logicalRunId: managedLogicalRunOwner ?? runId,
				generation: continuationGeneration,
				isCurrent: () => this.#continuationGeneration === continuationGeneration && this.#activeRunId === undefined,
			};
			if (this.#activeRunId === runId) {
				this.#state.isStreaming = false;
				this.#state.streamMessage = null;
				this.#state.pendingToolCalls = new Set<string>();
				this.#abortController = undefined;
				this.#activeRunId = undefined;
				this.#activeFallbackManaged = false;
				this.#resolveRunningPrompt?.();
				this.#runningPrompt = undefined;
				this.#resolveRunningPrompt = undefined;
			}
			if (
				fallbackManaged &&
				!continuation &&
				!maintenanceInterrupted &&
				this.#managedLogicalRunOwner === managedLogicalRunOwner
			) {
				this.#managedLogicalRunOwner = undefined;
			}
			if (continuation && ownership.isCurrent()) {
				try {
					await continuation(ownership);
					if (
						managedDecision?.type === "maintenance" &&
						this.#terminalizedLogicalRunIds.has(managedLogicalRunOwner ?? runId) &&
						this.#managedLogicalRunOwner === managedLogicalRunOwner
					) {
						this.#managedLogicalRunOwner = undefined;
					}
					if (
						managedDecision?.type !== "maintenance" &&
						this.#activeRunId === undefined &&
						this.#managedLogicalRunOwner === managedLogicalRunOwner
					) {
						this.#managedLogicalRunOwner = undefined;
					}
				} catch (err) {
					if (ownership.isCurrent()) {
						this.#state.error = err instanceof Error ? err.message : String(err);
						this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: "error" });
						if (this.#managedLogicalRunOwner === managedLogicalRunOwner) this.#managedLogicalRunOwner = undefined;
					}
				}
			}
		}
	}

	#emit(e: AgentEvent) {
		for (const listener of this.#listeners) {
			listener(e);
		}
	}

	/** Calculate total text length from an assistant message's content blocks */
	#finalizeRun(
		logicalRunId: ManagedLogicalRunId,
		event?: Extract<AgentEvent, { type: "agent_end" }>,
		beforeEvent?: () => void,
	): void {
		if (this.#terminalizedLogicalRunIds.has(logicalRunId)) return;
		this.#terminalizedLogicalRunIds.add(logicalRunId);
		if (this.#terminalizedLogicalRunIds.size > 256) {
			this.#terminalizedLogicalRunIds.delete(this.#terminalizedLogicalRunIds.values().next().value!);
		}
		beforeEvent?.();
		if (event) this.#emit(event);
	}

	#getAssistantTextLength(message: AgentMessage | null): number {
		if (message?.role !== "assistant" || !Array.isArray(message.content)) {
			return 0;
		}
		let length = 0;
		for (const block of message.content) {
			if (block.type === "text") {
				length += (block as TextContent).text.length;
			}
		}
		return length;
	}

	/**
	 * Emit a Cursor assistant message split around tool results.
	 * This fixes the ordering issue where tool results appear after the full explanation.
	 *
	 * Output order: Assistant(preamble) -> ToolResults -> Assistant(continuation)
	 */
	#emitCursorSplitAssistantMessage(assistantMessage: AssistantMessage): void {
		const buffer = this.#cursorToolResultBuffer;
		this.#cursorToolResultBuffer = [];

		if (buffer.length === 0) {
			// No tool results, emit normally
			this.#state.streamMessage = null;
			this.appendMessage(assistantMessage);
			this.#emit({ type: "message_end", message: assistantMessage });
			return;
		}

		// Find the split point: minimum text length at first tool call
		const splitPoint = Math.min(...buffer.map(r => r.textLengthAtCall));

		// Extract text content from assistant message
		const content = assistantMessage.content;
		let fullText = "";
		for (const block of content) {
			if (block.type === "text") {
				fullText += block.text;
			}
		}

		// If no text or split point is 0 or at/past end, don't split
		if (fullText.length === 0 || splitPoint <= 0 || splitPoint >= fullText.length) {
			// Emit assistant message first, then tool results (original behavior but with buffered results)
			this.#state.streamMessage = null;
			this.appendMessage(assistantMessage);
			this.#emit({ type: "message_end", message: assistantMessage });

			// Emit buffered tool results
			for (const { toolResult } of buffer) {
				this.#emit({ type: "message_start", message: toolResult });
				this.appendMessage(toolResult);
				this.#emit({ type: "message_end", message: toolResult });
			}
			return;
		}

		// Split the text
		const preambleText = fullText.slice(0, splitPoint);
		const continuationText = fullText.slice(splitPoint);

		// Create preamble message (text before tools)
		const preambleContent = content.map(block => {
			if (block.type === "text") {
				return { ...block, text: preambleText };
			}
			return block;
		});
		const preambleMessage: AssistantMessage = {
			...assistantMessage,
			content: preambleContent,
		};

		// Emit preamble
		this.#state.streamMessage = null;
		this.appendMessage(preambleMessage);
		this.#emit({ type: "message_end", message: preambleMessage });

		// Emit buffered tool results
		for (const { toolResult } of buffer) {
			this.#emit({ type: "message_start", message: toolResult });
			this.appendMessage(toolResult);
			this.#emit({ type: "message_end", message: toolResult });
		}

		// Emit continuation message (text after tools) if non-empty
		const trimmedContinuation = continuationText.trim();
		if (trimmedContinuation.length > 0) {
			// Create continuation message with only text content (no thinking/toolCalls)
			const continuationContent: TextContent[] = [{ type: "text", text: continuationText }];
			const continuationMessage: AssistantMessage = {
				...assistantMessage,
				content: continuationContent,
				// Zero out usage for continuation since it's part of same response
				usage: {
					input: 0,
					output: 0,
					cacheRead: 0,
					cacheWrite: 0,
					totalTokens: 0,
					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
				},
			};
			this.#emit({ type: "message_start", message: continuationMessage });
			this.appendMessage(continuationMessage);
			this.#emit({ type: "message_end", message: continuationMessage });
		}
	}
}