codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/sdk/packages/agents/src/agent-runtime.ts

@@ -0,0 +1,1558 @@
+import { createGateway } from "@cline/llms";
+import type {
+	AgentAfterToolResult,
+	AgentBeforeModelResult,
+	AgentBeforeToolResult,
+	AgentMessage,
+	AgentMessagePart,
+	AgentModel,
+	AgentModelFinishReason,
+	AgentModelRequest,
+	AgentRunResult,
+	AgentRuntimeEvent,
+	AgentRuntimeHooks,
+	AgentRuntimeStateSnapshot,
+	AgentStopControl,
+	AgentTool,
+	AgentToolCallPart,
+	AgentToolDefinition,
+	AgentToolResult,
+	AgentUsage,
+	AgentRuntimeConfig as BaseAgentRuntimeConfig,
+	TelemetryProperties,
+	ToolApprovalResult,
+	ToolPolicy,
+} from "@cline/shared";
+import { captureSdkError, estimateTokens } from "@cline/shared";
+import { nanoid } from "nanoid";
+
+// Local `createUID` helper. The clinee source imports this from
+// `@cline/shared` (see `packages/shared/dist/identifier.ts`), but
+// sdk-re's shared package does not expose it yet. Inlining here keeps
+// PLAN.md Step 1 scoped to `packages/agents/src/` and matches the
+// exact clinee implementation (`${prefix}_${nanoid(length)}`).
+function createUID(prefix: string, length = 8): string {
+	return `${prefix}_${nanoid(length)}`;
+}
+
+export type AgentRunInput = string | AgentMessage | readonly AgentMessage[];
+export type AgentEventListener = (event: AgentRuntimeEvent) => void;
+
+/**
+ * Advanced form: caller supplies a pre-built `AgentModel`. Used by
+ * `@cline/core`, which constructs models itself to share gateway/telemetry
+ * wiring with the rest of the session runtime.
+ */
+export interface AgentRuntimeConfigWithModel extends BaseAgentRuntimeConfig {
+	model: AgentModel;
+}
+
+/**
+ * Friendly form: caller supplies provider/model IDs and credentials, and the
+ * runtime builds an `AgentModel` internally via `@cline/llms`. This is the
+ * entry point most standalone users want.
+ */
+export interface AgentRuntimeConfigWithProvider
+	extends Omit<BaseAgentRuntimeConfig, "model"> {
+	/** Provider ID (e.g., "anthropic", "openai") */
+	providerId: string;
+	/** Model ID to use */
+	modelId: string;
+	/** API key for the provider */
+	apiKey?: string;
+	/** Custom base URL for the API */
+	baseUrl?: string;
+	/** Additional headers for API requests */
+	headers?: Record<string, string>;
+}
+
+/**
+ * Config accepted by `new AgentRuntime(...)` / `createAgentRuntime(...)` /
+ * `new Agent(...)` / `createAgent(...)`. Either supply a pre-built `model`
+ * (advanced) or `providerId` + `modelId` (+ credentials) and the runtime will
+ * construct the model itself via `@cline/llms`.
+ */
+export type AgentRuntimeConfig =
+	| AgentRuntimeConfigWithModel
+	| AgentRuntimeConfigWithProvider;
+
+function hasPrebuiltModel(
+	config: AgentRuntimeConfig,
+): config is AgentRuntimeConfigWithModel {
+	return (config as AgentRuntimeConfigWithModel).model !== undefined;
+}
+
+function resolveRuntimeConfig(
+	config: AgentRuntimeConfig,
+): BaseAgentRuntimeConfig {
+	if (hasPrebuiltModel(config)) {
+		return config;
+	}
+	const { providerId, modelId, apiKey, baseUrl, headers, ...rest } = config;
+	const gateway = createGateway({
+		providerConfigs: [{ providerId, apiKey, baseUrl, headers }],
+		telemetry: rest.telemetry,
+	});
+	const model = gateway.createAgentModel({ providerId, modelId });
+	return { ...rest, model };
+}
+
+function resolveToolPolicy(
+	toolName: string,
+	policies: BaseAgentRuntimeConfig["toolPolicies"],
+): ToolPolicy {
+	return {
+		...(policies?.["*"] ?? {}),
+		...(policies?.[toolName] ?? {}),
+	};
+}
+
+interface PendingToolAssembly {
+	toolCallId: string;
+	toolName?: string;
+	inputText: string;
+	inputValue?: unknown;
+	metadata?: unknown;
+	parseError?: string;
+}
+
+interface InvalidToolCall {
+	toolCallId: string;
+	toolName?: string;
+	input: Record<string, unknown>;
+	reason: "missing_name" | "missing_arguments" | "invalid_arguments";
+}
+
+function safeJsonSize(value: unknown): number {
+	try {
+		return JSON.stringify(value).length;
+	} catch {
+		return String(value).length;
+	}
+}
+
+function getOutputSize(output: unknown): number {
+	if (typeof output === "string") {
+		return output.length;
+	}
+	return safeJsonSize(output);
+}
+
+function summarizeModelRequest(
+	request: AgentModelRequest,
+): Record<string, unknown> {
+	let textChars = request.systemPrompt?.length ?? 0;
+	let toolResultCount = 0;
+	let toolResultChars = 0;
+	let maxToolResultChars = 0;
+	for (const message of request.messages) {
+		for (const part of message.content) {
+			switch (part.type) {
+				case "text":
+					textChars += part.text.length;
+					break;
+				case "reasoning":
+					textChars += part.text.length;
+					break;
+				case "file":
+					textChars += part.content.length;
+					break;
+				case "tool-call":
+					textChars += safeJsonSize(part.input);
+					break;
+				case "tool-result": {
+					const outputChars = getOutputSize(part.output);
+					toolResultCount += 1;
+					toolResultChars += outputChars;
+					maxToolResultChars = Math.max(maxToolResultChars, outputChars);
+					textChars += outputChars;
+					break;
+				}
+			}
+		}
+	}
+
+	return {
+		messageCount: request.messages.length,
+		toolSchemaCount: request.tools.length,
+		systemPromptChars: request.systemPrompt?.length ?? 0,
+		requestJsonChars: safeJsonSize({
+			systemPrompt: request.systemPrompt,
+			messages: request.messages,
+			tools: request.tools,
+			options: request.options,
+		}),
+		visibleTextChars: textChars,
+		estimatedTextTokens: estimateTokens(textChars),
+		toolResultCount,
+		toolResultChars,
+		maxToolResultChars,
+	};
+}
+
+interface PreparedToolExecution {
+	toolCall: AgentToolCallPart;
+	tool?: AgentTool;
+	input: unknown;
+	skipReason?: string;
+}
+
+interface HookBag {
+	beforeRun: NonNullable<AgentRuntimeHooks["beforeRun"]>[];
+	afterRun: NonNullable<AgentRuntimeHooks["afterRun"]>[];
+	beforeModel: NonNullable<AgentRuntimeHooks["beforeModel"]>[];
+	afterModel: NonNullable<AgentRuntimeHooks["afterModel"]>[];
+	beforeTool: NonNullable<AgentRuntimeHooks["beforeTool"]>[];
+	afterTool: NonNullable<AgentRuntimeHooks["afterTool"]>[];
+	onEvent: NonNullable<AgentRuntimeHooks["onEvent"]>[];
+}
+
+class ControlledStopError extends Error {
+	readonly reason?: string;
+
+	constructor(reason?: string) {
+		super(reason ?? "Run stopped by runtime control");
+		this.name = "ControlledStopError";
+		this.reason = reason;
+	}
+}
+
+export class AgentRuntimeAbortError extends Error {
+	readonly reason?: unknown;
+
+	constructor(reason?: unknown) {
+		const message =
+			typeof reason === "string"
+				? reason
+				: reason instanceof Error
+					? reason.message
+					: reason === undefined
+						? "Run aborted"
+						: String(reason);
+		super(message);
+		this.name = "AgentRuntimeAbortError";
+		this.reason = reason;
+	}
+}
+
+const DEFAULT_USAGE: AgentUsage = {
+	inputTokens: 0,
+	outputTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0,
+};
+
+function createMessage(
+	role: AgentMessage["role"],
+	content: AgentMessagePart[],
+	metadata?: Record<string, unknown>,
+): AgentMessage {
+	return {
+		id: createUID("msg"),
+		role,
+		content,
+		createdAt: Date.now(),
+		metadata,
+	};
+}
+
+function cloneUsage(usage: AgentUsage): AgentUsage {
+	return { ...usage };
+}
+
+function cloneMessages(messages: readonly AgentMessage[]): AgentMessage[] {
+	return messages.map((message) => ({
+		...message,
+		content: message.content.map((part: AgentMessagePart) => ({ ...part })),
+		metadata: message.metadata ? { ...message.metadata } : undefined,
+		modelInfo: message.modelInfo ? { ...message.modelInfo } : undefined,
+		metrics: message.metrics ? { ...message.metrics } : undefined,
+	}));
+}
+
+function usageDelta(
+	start: AgentUsage,
+	end: AgentUsage,
+): NonNullable<AgentMessage["metrics"]> | undefined {
+	const inputTokens = Math.max(
+		0,
+		(end.inputTokens ?? 0) - (start.inputTokens ?? 0),
+	);
+	const outputTokens = Math.max(
+		0,
+		(end.outputTokens ?? 0) - (start.outputTokens ?? 0),
+	);
+	const cacheReadTokens = Math.max(
+		0,
+		(end.cacheReadTokens ?? 0) - (start.cacheReadTokens ?? 0),
+	);
+	const cacheWriteTokens = Math.max(
+		0,
+		(end.cacheWriteTokens ?? 0) - (start.cacheWriteTokens ?? 0),
+	);
+	const startCost = start.totalCost ?? 0;
+	const endCost = end.totalCost ?? 0;
+	const cost = Math.max(0, endCost - startCost);
+	if (
+		inputTokens === 0 &&
+		outputTokens === 0 &&
+		cacheReadTokens === 0 &&
+		cacheWriteTokens === 0 &&
+		cost === 0
+	) {
+		return undefined;
+	}
+	return {
+		inputTokens: inputTokens > 0 ? inputTokens : 0,
+		outputTokens: outputTokens > 0 ? outputTokens : 0,
+		cacheReadTokens: cacheReadTokens > 0 ? cacheReadTokens : 0,
+		cacheWriteTokens: cacheWriteTokens > 0 ? cacheWriteTokens : 0,
+		...(cost > 0 ? { cost } : {}),
+	};
+}
+
+function textFromMessage(message: AgentMessage | undefined): string {
+	if (!message) {
+		return "";
+	}
+	return message.content
+		.filter(
+			(
+				part: AgentMessagePart,
+			): part is Extract<AgentMessagePart, { type: "text" }> =>
+				part.type === "text",
+		)
+		.map((part: Extract<AgentMessagePart, { type: "text" }>) => part.text)
+		.join("");
+}
+
+function textFromToolMessage(message: AgentMessage | undefined): string {
+	const result = message?.content.find(
+		(part): part is Extract<AgentMessagePart, { type: "tool-result" }> =>
+			part.type === "tool-result",
+	);
+	if (!result || result.isError) {
+		return "";
+	}
+	if (typeof result.output === "string") {
+		return result.output;
+	}
+	try {
+		return JSON.stringify(result.output);
+	} catch {
+		return String(result.output);
+	}
+}
+
+function normalizeInput(input: AgentRunInput): AgentMessage[] {
+	if (typeof input === "string") {
+		return [createMessage("user", [{ type: "text", text: input }])];
+	}
+	if (Array.isArray(input)) {
+		return cloneMessages(input);
+	}
+	return cloneMessages([input as AgentMessage]);
+}
+
+export class AgentRuntime {
+	private config: Required<Pick<BaseAgentRuntimeConfig, "toolExecution">> &
+		BaseAgentRuntimeConfig;
+	private readonly listeners = new Set<AgentEventListener>();
+	// biome-ignore lint/suspicious/noExplicitAny: tool input/output types vary per tool
+	private readonly tools = new Map<string, AgentTool<any, any>>();
+	private hooks: HookBag = {
+		beforeRun: [],
+		afterRun: [],
+		beforeModel: [],
+		afterModel: [],
+		beforeTool: [],
+		afterTool: [],
+		onEvent: [],
+	};
+	private readonly state = {
+		agentId: "",
+		agentRole: undefined as string | undefined,
+		parentAgentId: undefined as string | null | undefined,
+		runId: undefined as string | undefined,
+		status: "idle" as AgentRuntimeStateSnapshot["status"],
+		iteration: 0,
+		messages: [] as AgentMessage[],
+		pendingToolCalls: [] as string[],
+		usage: cloneUsage(DEFAULT_USAGE),
+		lastError: undefined as string | undefined,
+	};
+	private initialization?: Promise<void>;
+	private abortController?: AbortController;
+
+	constructor(config: AgentRuntimeConfig) {
+		const resolved = resolveRuntimeConfig(config);
+		this.config = {
+			...resolved,
+			toolExecution: resolved.toolExecution ?? "sequential",
+		};
+		this.state.agentId = resolved.agentId ?? createUID("agent");
+		this.state.agentRole = resolved.agentRole;
+		this.state.parentAgentId = resolved.parentAgentId;
+		this.state.messages = cloneMessages(resolved.initialMessages ?? []);
+	}
+
+	async run(input: AgentRunInput): Promise<AgentRunResult> {
+		return this.execute(input);
+	}
+
+	async continue(input?: AgentRunInput): Promise<AgentRunResult> {
+		return this.execute(input);
+	}
+
+	abort(reason?: unknown): void {
+		if (!this.abortController) {
+			return;
+		}
+		const abortError =
+			reason instanceof AgentRuntimeAbortError
+				? reason
+				: new AgentRuntimeAbortError(reason);
+		this.state.lastError = abortError.message;
+		this.abortController.abort(abortError);
+	}
+
+	subscribe(listener: AgentEventListener): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	/**
+	 * Replace the conversation with a fresh set of messages, discarding any
+	 * in-flight run and usage state while preserving the underlying model,
+	 * tools, hooks, plugins, and active event subscribers.
+	 *
+	 * Useful for standalone callers that persist conversations externally and
+	 * want to re-seed the runtime from storage without recreating subscribers.
+	 */
+	restore(messages: readonly AgentMessage[]): void {
+		this.abort("Agent state restored");
+		// Reset state that is not carried across restores. Keep `listeners`,
+		// tools, hooks, plugins, model, and agent identity so external event
+		// subscribers continue to receive events after restore().
+		this.state.runId = undefined;
+		this.state.status = "idle";
+		this.state.iteration = 0;
+		this.state.pendingToolCalls = [];
+		this.state.usage = cloneUsage(DEFAULT_USAGE);
+		this.state.lastError = undefined;
+		this.state.messages = cloneMessages(messages);
+		this.config = {
+			...this.config,
+			initialMessages: cloneMessages(messages),
+		};
+	}
+
+	snapshot(): AgentRuntimeStateSnapshot {
+		return {
+			agentId: this.state.agentId,
+			agentRole: this.state.agentRole,
+			parentAgentId: this.state.parentAgentId,
+			conversationId: this.config.conversationId?.trim() || undefined,
+			runId: this.state.runId,
+			status: this.state.status,
+			iteration: this.state.iteration,
+			messages: cloneMessages(this.state.messages),
+			pendingToolCalls: [...this.state.pendingToolCalls],
+			usage: cloneUsage(this.state.usage),
+			lastError: this.state.lastError,
+		};
+	}
+
+	private async ensureInitialized(): Promise<void> {
+		this.initialization ??= this.initialize();
+		await this.initialization;
+	}
+
+	private async initialize(): Promise<void> {
+		this.registerHooks(this.config.hooks);
+		for (const tool of this.config.tools ?? []) {
+			this.tools.set(tool.name, tool);
+		}
+		for (const plugin of this.config.plugins ?? []) {
+			const setup = await plugin.setup?.({
+				agentId: this.state.agentId,
+				agentRole: this.state.agentRole,
+				systemPrompt: this.config.systemPrompt,
+			});
+			for (const tool of setup?.tools ?? []) {
+				this.tools.set(tool.name, tool);
+			}
+			this.registerHooks(setup?.hooks);
+		}
+	}
+
+	private registerHooks(hooks: Partial<AgentRuntimeHooks> | undefined): void {
+		if (!hooks) {
+			return;
+		}
+		if (hooks.beforeRun) this.hooks.beforeRun.push(hooks.beforeRun);
+		if (hooks.afterRun) this.hooks.afterRun.push(hooks.afterRun);
+		if (hooks.beforeModel) this.hooks.beforeModel.push(hooks.beforeModel);
+		if (hooks.afterModel) this.hooks.afterModel.push(hooks.afterModel);
+		if (hooks.beforeTool) this.hooks.beforeTool.push(hooks.beforeTool);
+		if (hooks.afterTool) this.hooks.afterTool.push(hooks.afterTool);
+		if (hooks.onEvent) this.hooks.onEvent.push(hooks.onEvent);
+	}
+
+	private getRequiredCompletionToolNames(): string[] {
+		if (this.config.completionPolicy?.requireCompletionTool !== true) {
+			return [];
+		}
+		return [...this.tools.values()]
+			.filter((tool) => tool.lifecycle?.completesRun === true)
+			.map((tool) => tool.name)
+			.sort();
+	}
+
+	private getCompletionToolReminderMessage(): string | undefined {
+		const terminalToolNames = this.getRequiredCompletionToolNames();
+		if (terminalToolNames.length === 0) {
+			return undefined;
+		}
+		return `[SYSTEM] This run is not complete until you call one of these terminal completion tools: ${terminalToolNames.join(
+			", ",
+		)}. Continue working if requirements are not met. If the task is complete, call the appropriate terminal completion tool now.`;
+	}
+
+	private getCompletionReminderMessages(): string[] {
+		return [
+			this.getCompletionToolReminderMessage(),
+			this.config.completionPolicy?.completionGuard?.(),
+		].filter((message): message is string => Boolean(message));
+	}
+
+	private async addUserReminderMessage(text: string): Promise<AgentMessage> {
+		const reminderMessage = createMessage("user", [{ type: "text", text }]);
+		this.state.messages.push(reminderMessage);
+		await this.emit({
+			type: "message-added",
+			snapshot: this.snapshot(),
+			message: reminderMessage,
+		});
+		return reminderMessage;
+	}
+
+	private async execute(input?: AgentRunInput): Promise<AgentRunResult> {
+		await this.ensureInitialized();
+		if (this.state.status === "running") {
+			throw new Error("Agent runtime is already running");
+		}
+
+		this.abortController = new AbortController();
+		this.state.runId = createUID("run");
+		this.state.status = "running";
+		this.state.iteration = 0;
+		this.state.pendingToolCalls = [];
+		this.state.lastError = undefined;
+		this.state.usage = cloneUsage(DEFAULT_USAGE);
+
+		try {
+			await this.callBeforeRunHooks();
+			await this.emit({ type: "run-started", snapshot: this.snapshot() });
+
+			for (const message of input ? normalizeInput(input) : []) {
+				this.state.messages.push(message);
+				await this.emit({
+					type: "message-added",
+					snapshot: this.snapshot(),
+					message,
+				});
+			}
+
+			const completionToolReminder = this.getCompletionToolReminderMessage();
+			if (completionToolReminder) {
+				await this.addUserReminderMessage(completionToolReminder);
+			}
+
+			let finalAssistantMessage: AgentMessage | undefined;
+
+			while (
+				this.config.maxIterations === undefined ||
+				this.state.iteration < this.config.maxIterations
+			) {
+				this.throwIfAborted();
+
+				this.state.iteration += 1;
+				await this.emit({
+					type: "turn-started",
+					snapshot: this.snapshot(),
+					iteration: this.state.iteration,
+				});
+
+				const { message, finishReason } = await this.generateAssistantMessage();
+				finalAssistantMessage = message;
+				this.state.messages.push(message);
+				await this.emit({
+					type: "message-added",
+					snapshot: this.snapshot(),
+					message,
+				});
+				await this.emit({
+					type: "assistant-message",
+					snapshot: this.snapshot(),
+					iteration: this.state.iteration,
+					message,
+					finishReason,
+				});
+
+				if (finishReason === "aborted") {
+					throw this.normalizeAbortError();
+				}
+
+				const toolCalls = message.content.filter(
+					(part: AgentMessagePart): part is AgentToolCallPart =>
+						part.type === "tool-call",
+				);
+				if (finishReason === "error" && toolCalls.length === 0) {
+					throw new Error(this.state.lastError ?? "Model stream failed");
+				}
+				this.state.pendingToolCalls = toolCalls.map((part) => part.toolCallId);
+
+				if (toolCalls.length === 0) {
+					await this.emit({
+						type: "turn-finished",
+						snapshot: this.snapshot(),
+						iteration: this.state.iteration,
+						toolCallCount: 0,
+					});
+					const completionReminderMessages =
+						this.getCompletionReminderMessages();
+					if (completionReminderMessages.length > 0) {
+						for (const reminderMessage of completionReminderMessages) {
+							await this.addUserReminderMessage(reminderMessage);
+						}
+						continue;
+					}
+					const result = this.finishRun("completed", finalAssistantMessage);
+					await this.callAfterRunHooks(result);
+					await this.emit({
+						type: "run-finished",
+						snapshot: this.snapshot(),
+						result,
+					});
+					return result;
+				}
+
+				const toolMessages = await this.executeToolCalls(toolCalls);
+				this.state.pendingToolCalls = [];
+				for (const toolMessage of toolMessages) {
+					this.state.messages.push(toolMessage);
+					await this.emit({
+						type: "message-added",
+						snapshot: this.snapshot(),
+						message: toolMessage,
+					});
+				}
+				await this.emit({
+					type: "turn-finished",
+					snapshot: this.snapshot(),
+					iteration: this.state.iteration,
+					toolCallCount: toolCalls.length,
+				});
+				const terminalToolMessage = this.findCompletingToolMessage(
+					toolCalls,
+					toolMessages,
+				);
+				if (terminalToolMessage) {
+					const result = this.finishRun(
+						"completed",
+						finalAssistantMessage,
+						textFromToolMessage(terminalToolMessage) || undefined,
+					);
+					await this.callAfterRunHooks(result);
+					await this.emit({
+						type: "run-finished",
+						snapshot: this.snapshot(),
+						result,
+					});
+					return result;
+				}
+			}
+
+			throw new Error(
+				`Agent runtime exceeded maxIterations (${this.config.maxIterations})`,
+			);
+		} catch (error) {
+			const normalized =
+				error instanceof Error ? error : new Error(String(error));
+			const isControlledStop = normalized instanceof ControlledStopError;
+			const status =
+				this.abortController.signal.aborted || isControlledStop
+					? "aborted"
+					: "failed";
+			this.state.status = status;
+			this.state.lastError = normalized.message;
+			const result: AgentRunResult = {
+				agentId: this.state.agentId,
+				agentRole: this.state.agentRole,
+				runId: this.state.runId ?? createUID("run"),
+				status,
+				iterations: this.state.iteration,
+				outputText: textFromMessage(this.findLastAssistantMessage()),
+				messages: cloneMessages(this.state.messages),
+				usage: cloneUsage(this.state.usage),
+				error: status === "failed" ? normalized : undefined,
+			};
+			await this.callAfterRunHooks(result);
+			if (status === "failed") {
+				await this.emit({
+					type: "run-failed",
+					snapshot: this.snapshot(),
+					error: normalized,
+				});
+			} else {
+				await this.emit({
+					type: "run-finished",
+					snapshot: this.snapshot(),
+					result,
+				});
+			}
+			return result;
+		} finally {
+			this.abortController = undefined;
+		}
+	}
+
+	private async callBeforeRunHooks(): Promise<void> {
+		for (const hook of this.hooks.beforeRun) {
+			const control = (await hook({
+				snapshot: this.snapshot(),
+			})) as AgentStopControl | undefined;
+			this.applyStopControl(control);
+		}
+	}
+
+	private async callAfterRunHooks(result: AgentRunResult): Promise<void> {
+		for (const hook of this.hooks.afterRun) {
+			await hook({ snapshot: this.snapshot(), result });
+		}
+	}
+
+	private async generateAssistantMessage(): Promise<{
+		message: AgentMessage;
+		finishReason: AgentModelFinishReason;
+	}> {
+		const usageBeforeModel = cloneUsage(this.state.usage);
+		let request: AgentModelRequest = {
+			systemPrompt: this.config.systemPrompt,
+			messages: cloneMessages(this.state.messages),
+			tools: [...this.tools.values()].map<AgentToolDefinition>((tool) => ({
+				name: tool.name,
+				description: tool.description,
+				inputSchema: tool.inputSchema,
+			})),
+			signal: this.abortController?.signal,
+			options: this.config.modelOptions,
+		};
+
+		if (this.state.iteration > 1) {
+			if (await this.consumePendingUserMessage()) {
+				request = { ...request, messages: cloneMessages(this.state.messages) };
+			}
+		}
+
+		request = await this.prepareTurnForModelRequest(request);
+
+		for (const hook of this.hooks.beforeModel) {
+			const result = (await hook({
+				snapshot: this.snapshot(),
+				request,
+			})) as AgentBeforeModelResult | undefined;
+			this.applyStopControl(result);
+			if (result?.messages) {
+				request = { ...request, messages: cloneMessages(result.messages) };
+			}
+			if (result?.tools) {
+				request = { ...request, tools: [...result.tools] };
+			}
+			if (result?.options) {
+				request = {
+					...request,
+					options: { ...(request.options ?? {}), ...result.options },
+				};
+			}
+		}
+
+		this.config.logger?.debug("Agent model request diagnostics", {
+			iteration: this.state.iteration,
+			providerId:
+				"providerId" in this.config &&
+				typeof this.config.providerId === "string"
+					? this.config.providerId
+					: undefined,
+			modelId:
+				"modelId" in this.config && typeof this.config.modelId === "string"
+					? this.config.modelId
+					: undefined,
+			...summarizeModelRequest(request),
+		});
+
+		const stream = await this.config.model.stream(request);
+		const content: AgentMessagePart[] = [];
+		const toolAssemblies = new Map<string, PendingToolAssembly>();
+		const invalidToolCalls: InvalidToolCall[] = [];
+		const sequence: Array<
+			{ type: "tool"; key: string } | { type: "part"; part: AgentMessagePart }
+		> = [];
+		let nextToolIndex = 0;
+		let finishReason: AgentModelFinishReason = "stop";
+		let accumulatedText = "";
+		let accumulatedReasoning = "";
+
+		for await (const event of stream) {
+			this.throwIfAborted();
+			switch (event.type) {
+				case "text-delta": {
+					accumulatedText += event.text;
+					const last = sequence.at(-1);
+					if (last?.type === "part" && last.part.type === "text") {
+						last.part.text += event.text;
+					} else {
+						sequence.push({
+							type: "part",
+							part: { type: "text", text: event.text },
+						});
+					}
+					await this.emit({
+						type: "assistant-text-delta",
+						snapshot: this.snapshot(),
+						iteration: this.state.iteration,
+						text: event.text,
+						accumulatedText,
+					});
+					break;
+				}
+				case "reasoning-delta": {
+					accumulatedReasoning += event.text;
+					const last = sequence.at(-1);
+					if (last?.type === "part" && last.part.type === "reasoning") {
+						last.part.text += event.text;
+						last.part.redacted = event.redacted ?? last.part.redacted;
+						last.part.metadata = event.metadata ?? last.part.metadata;
+					} else {
+						sequence.push({
+							type: "part",
+							part: {
+								type: "reasoning",
+								text: event.text,
+								redacted: event.redacted,
+								metadata: event.metadata,
+							},
+						});
+					}
+					await this.emit({
+						type: "assistant-reasoning-delta",
+						snapshot: this.snapshot(),
+						iteration: this.state.iteration,
+						text: event.text,
+						accumulatedText: accumulatedReasoning,
+						redacted: event.redacted,
+						metadata: event.metadata,
+					});
+					break;
+				}
+				case "tool-call-delta": {
+					const key =
+						event.toolCallId ?? `tool_${event.index ?? nextToolIndex}`;
+					if (event.index == null && event.toolCallId == null) {
+						nextToolIndex += 1;
+					}
+					let assembly = toolAssemblies.get(key);
+					if (!assembly) {
+						assembly = {
+							toolCallId: event.toolCallId ?? createUID("tool"),
+							inputText: "",
+						};
+						toolAssemblies.set(key, assembly);
+						sequence.push({ type: "tool", key });
+					}
+					if (event.toolCallId) {
+						assembly.toolCallId = event.toolCallId;
+					}
+					if (event.toolName) {
+						assembly.toolName = event.toolName;
+					}
+					if (event.input !== undefined) {
+						assembly.inputValue = event.input;
+					}
+					if (event.metadata !== undefined) {
+						assembly.metadata = mergeToolMetadata(
+							assembly.metadata,
+							event.metadata,
+						);
+					}
+					if (event.inputText) {
+						assembly.inputText = mergeToolInputText(
+							assembly.inputText,
+							event.inputText,
+						);
+					}
+					break;
+				}
+				case "usage": {
+					await this.updateUsage(event.usage);
+					break;
+				}
+				case "finish": {
+					finishReason = event.reason;
+					if (event.error) {
+						this.state.lastError = event.error;
+					}
+					break;
+				}
+			}
+		}
+
+		for (const item of sequence) {
+			if (item.type === "part") {
+				content.push(item.part);
+				continue;
+			}
+			const assembly = toolAssemblies.get(item.key);
+			if (!assembly?.toolName) {
+				invalidToolCalls.push({
+					toolCallId: assembly?.toolCallId ?? item.key,
+					input: buildInvalidToolInput(assembly?.inputText ?? ""),
+					reason: "missing_name",
+				});
+				continue;
+			}
+			const parsed = parseToolInput(assembly);
+			if (parsed.reason) {
+				invalidToolCalls.push({
+					toolCallId: assembly.toolCallId,
+					toolName: assembly.toolName,
+					input: parsed.invalidInput,
+					reason: parsed.reason,
+				});
+			}
+			content.push({
+				type: "tool-call",
+				toolCallId: assembly.toolCallId,
+				toolName: assembly.toolName,
+				input: parsed.input,
+				metadata: parsed.parseError
+					? mergeToolMetadata(assembly.metadata, {
+							inputParseError: parsed.parseError,
+							rawInputText: assembly.inputText,
+						})
+					: assembly.metadata,
+			});
+		}
+
+		const message = createMessage(
+			"assistant",
+			content,
+			invalidToolCalls.length > 0 ? { invalidToolCalls } : undefined,
+		);
+		const metrics = usageDelta(usageBeforeModel, this.state.usage);
+		if (metrics) {
+			message.metrics = metrics;
+		}
+		if (this.config.messageModelInfo) {
+			message.modelInfo = { ...this.config.messageModelInfo };
+		}
+		for (const hook of this.hooks.afterModel) {
+			const control = (await hook({
+				snapshot: this.snapshot(),
+				assistantMessage: message,
+				finishReason,
+			})) as AgentStopControl | undefined;
+			this.applyStopControl(control);
+		}
+
+		return { message, finishReason };
+	}
+
+	private async prepareTurnForModelRequest(
+		request: AgentModelRequest,
+	): Promise<AgentModelRequest> {
+		if (!this.config.prepareTurn) {
+			return request;
+		}
+
+		const result = await this.config.prepareTurn({
+			agentId: this.state.agentId,
+			conversationId: this.config.conversationId,
+			parentAgentId: this.state.parentAgentId ?? null,
+			iteration: this.state.iteration,
+			messages: request.messages,
+			systemPrompt: request.systemPrompt,
+			tools: request.tools,
+			model: {
+				id: this.config.messageModelInfo?.id,
+				provider: this.config.messageModelInfo?.provider,
+			},
+			signal: request.signal,
+			emitStatusNotice: (message, metadata) => {
+				void this.emit({
+					type: "status-notice",
+					snapshot: this.snapshot(),
+					message,
+					metadata,
+				});
+			},
+		});
+		if (!result) {
+			return request;
+		}
+
+		let next = request;
+		if (result.messages) {
+			const preparedMessages = cloneMessages(result.messages);
+			this.state.messages = preparedMessages;
+			next = { ...next, messages: cloneMessages(preparedMessages) };
+		}
+		if (result.systemPrompt !== undefined) {
+			next = { ...next, systemPrompt: result.systemPrompt };
+		}
+		return next;
+	}
+
+	private async consumePendingUserMessage(): Promise<boolean> {
+		const consumePendingUserMessage = this.config.consumePendingUserMessage;
+		if (!consumePendingUserMessage) {
+			return false;
+		}
+		const pending = (await consumePendingUserMessage())?.trim();
+		if (!pending) {
+			return false;
+		}
+		const message = createMessage("user", [{ type: "text", text: pending }]);
+		this.state.messages.push(message);
+		await this.emit({
+			type: "message-added",
+			snapshot: this.snapshot(),
+			message,
+		});
+		return true;
+	}
+
+	private async updateUsage(usage: Partial<AgentUsage>): Promise<void> {
+		this.state.usage = {
+			inputTokens: this.state.usage.inputTokens + (usage.inputTokens ?? 0),
+			outputTokens: this.state.usage.outputTokens + (usage.outputTokens ?? 0),
+			cacheReadTokens:
+				this.state.usage.cacheReadTokens + (usage.cacheReadTokens ?? 0),
+			cacheWriteTokens:
+				this.state.usage.cacheWriteTokens + (usage.cacheWriteTokens ?? 0),
+			totalCost: (this.state.usage.totalCost ?? 0) + (usage.totalCost ?? 0),
+		};
+		await this.emit({
+			type: "usage-updated",
+			snapshot: this.snapshot(),
+			usage: cloneUsage(this.state.usage),
+		});
+	}
+
+	private async executeToolCalls(
+		toolCalls: AgentToolCallPart[],
+	): Promise<AgentMessage[]> {
+		const prepared: PreparedToolExecution[] = [];
+		for (const toolCall of toolCalls) {
+			prepared.push(await this.prepareToolExecution(toolCall));
+		}
+
+		if (this.config.toolExecution === "parallel") {
+			return Promise.all(
+				prepared.map((execution) => this.executePreparedTool(execution)),
+			);
+		}
+
+		const results: AgentMessage[] = [];
+		for (const execution of prepared) {
+			results.push(await this.executePreparedTool(execution));
+		}
+		return results;
+	}
+
+	private findCompletingToolMessage(
+		toolCalls: AgentToolCallPart[],
+		toolMessages: AgentMessage[],
+	): AgentMessage | undefined {
+		for (let index = 0; index < toolCalls.length; index += 1) {
+			const toolCall = toolCalls[index];
+			if (this.tools.get(toolCall.toolName)?.lifecycle?.completesRun !== true) {
+				continue;
+			}
+			const toolMessage = toolMessages[index];
+			const result = toolMessage?.content.find(
+				(part): part is Extract<AgentMessagePart, { type: "tool-result" }> =>
+					part.type === "tool-result" &&
+					part.toolCallId === toolCall.toolCallId,
+			);
+			if (result && !result.isError) {
+				return toolMessage;
+			}
+		}
+		return undefined;
+	}
+
+	private async prepareToolExecution(
+		toolCall: AgentToolCallPart,
+	): Promise<PreparedToolExecution> {
+		const tool = this.tools.get(toolCall.toolName);
+		let input = toolCall.input;
+		let skipReason: string | undefined;
+		const metadata =
+			toolCall.metadata &&
+			typeof toolCall.metadata === "object" &&
+			!Array.isArray(toolCall.metadata)
+				? (toolCall.metadata as Record<string, unknown>)
+				: undefined;
+
+		if (typeof metadata?.inputParseError === "string") {
+			skipReason = metadata.inputParseError;
+		}
+
+		const toolSource =
+			metadata?.toolSource &&
+			typeof metadata.toolSource === "object" &&
+			!Array.isArray(metadata.toolSource)
+				? (metadata.toolSource as Record<string, unknown>)
+				: undefined;
+		if (toolSource?.executionMode === "provider") {
+			const providerId =
+				typeof toolSource.providerId === "string"
+					? toolSource.providerId
+					: "provider";
+			skipReason = `Tool execution is disabled for provider ${providerId}`;
+		}
+
+		if (tool && !skipReason) {
+			for (const hook of this.hooks.beforeTool) {
+				const result = (await hook({
+					snapshot: this.snapshot(),
+					tool,
+					toolCall,
+					input,
+				})) as AgentBeforeToolResult | undefined;
+				if (result?.input !== undefined) {
+					input = result.input;
+				}
+				this.applyStopControl(result);
+				if (result?.skip) {
+					skipReason =
+						result.reason ?? `Tool ${tool.name} was blocked by a runtime hook`;
+					break;
+				}
+			}
+		}
+
+		if (tool && !skipReason) {
+			const policy = resolveToolPolicy(
+				toolCall.toolName,
+				this.config.toolPolicies,
+			);
+			if (policy.enabled === false) {
+				skipReason = `Tool "${toolCall.toolName}" is disabled by policy`;
+			} else if (policy.autoApprove === false) {
+				const approval = await this.requestToolApproval(
+					toolCall,
+					input,
+					policy,
+				);
+				if (!approval.approved) {
+					skipReason =
+						approval.reason ?? `Tool "${toolCall.toolName}" was not approved`;
+				}
+			}
+		}
+
+		return {
+			toolCall: { ...toolCall, input },
+			tool,
+			input,
+			skipReason,
+		};
+	}
+
+	private async requestToolApproval(
+		toolCall: AgentToolCallPart,
+		input: unknown,
+		policy: ToolPolicy,
+	): Promise<ToolApprovalResult> {
+		const requestApproval = this.config.requestToolApproval;
+		if (!requestApproval) {
+			return {
+				approved: false,
+				reason: `Tool "${toolCall.toolName}" requires approval but no approval callback is configured`,
+			};
+		}
+		try {
+			return await requestApproval({
+				sessionId:
+					this.config.sessionId?.trim() ||
+					this.config.conversationId?.trim() ||
+					this.state.runId ||
+					this.state.agentId,
+				agentId: this.state.agentId,
+				conversationId:
+					this.config.conversationId?.trim() ||
+					this.state.runId ||
+					this.state.agentId,
+				iteration: this.state.iteration,
+				toolCallId: toolCall.toolCallId,
+				toolName: toolCall.toolName,
+				input,
+				policy,
+			});
+		} catch (error) {
+			return {
+				approved: false,
+				reason: `Tool "${toolCall.toolName}" approval request failed: ${
+					error instanceof Error ? error.message : String(error)
+				}`,
+			};
+		}
+	}
+
+	private async executePreparedTool(
+		prepared: PreparedToolExecution,
+	): Promise<AgentMessage> {
+		const startedAt = new Date();
+		await this.emit({
+			type: "tool-started",
+			snapshot: this.snapshot(),
+			iteration: this.state.iteration,
+			toolCall: prepared.toolCall,
+		});
+
+		let result: AgentToolResult;
+		if (prepared.skipReason) {
+			result = {
+				output: { error: prepared.skipReason },
+				isError: true,
+			};
+		} else if (!prepared.tool) {
+			result = {
+				output: { error: `Unknown tool: ${prepared.toolCall.toolName}` },
+				isError: true,
+			};
+		} else {
+			try {
+				const output = await prepared.tool.execute(prepared.input, {
+					sessionId: this.config.sessionId,
+					agentId: this.state.agentId,
+					conversationId: this.config.conversationId,
+					runId: this.state.runId ?? createUID("run"),
+					iteration: this.state.iteration,
+					toolCallId: prepared.toolCall.toolCallId,
+					signal: this.abortController?.signal,
+					metadata: this.config.toolContextMetadata,
+					snapshot: this.snapshot(),
+					emitUpdate: (update: unknown) => {
+						void this.emit({
+							type: "tool-updated",
+							snapshot: this.snapshot(),
+							iteration: this.state.iteration,
+							toolCall: prepared.toolCall,
+							update,
+						});
+					},
+				});
+				result = { output };
+			} catch (error) {
+				result = {
+					output: {
+						error: error instanceof Error ? error.message : String(error),
+					},
+					isError: true,
+				};
+			}
+		}
+
+		const endedAt = new Date();
+		const durationMs = Math.max(0, endedAt.getTime() - startedAt.getTime());
+
+		if (prepared.tool) {
+			for (const hook of this.hooks.afterTool) {
+				const after = (await hook({
+					snapshot: this.snapshot(),
+					tool: prepared.tool,
+					toolCall: prepared.toolCall,
+					input: prepared.input,
+					result,
+					startedAt,
+					endedAt,
+					durationMs,
+				})) as AgentAfterToolResult | undefined;
+				this.applyStopControl(after);
+				if (after?.result) {
+					result = after.result;
+				}
+			}
+		}
+
+		const message = createMessage("tool", [
+			{
+				type: "tool-result",
+				toolCallId: prepared.toolCall.toolCallId,
+				toolName: prepared.toolCall.toolName,
+				output: result.output,
+				isError: result.isError,
+			},
+		]);
+
+		await this.emit({
+			type: "tool-finished",
+			snapshot: this.snapshot(),
+			iteration: this.state.iteration,
+			toolCall: prepared.toolCall,
+			message,
+		});
+
+		return message;
+	}
+
+	private finishRun(
+		status: AgentRunResult["status"],
+		assistantMessage?: AgentMessage,
+		outputText?: string,
+	): AgentRunResult {
+		this.state.status = status;
+		return {
+			agentId: this.state.agentId,
+			agentRole: this.state.agentRole,
+			runId: this.state.runId ?? createUID("run"),
+			status,
+			iterations: this.state.iteration,
+			outputText:
+				outputText ??
+				textFromMessage(assistantMessage ?? this.findLastAssistantMessage()),
+			messages: cloneMessages(this.state.messages),
+			usage: cloneUsage(this.state.usage),
+		};
+	}
+
+	private findLastAssistantMessage(): AgentMessage | undefined {
+		return [...this.state.messages]
+			.reverse()
+			.find((message) => message.role === "assistant");
+	}
+
+	private throwIfAborted(): void {
+		if (this.abortController?.signal.aborted) {
+			throw this.normalizeAbortError();
+		}
+	}
+
+	private normalizeAbortError(): Error {
+		const reason = this.abortController?.signal.reason;
+		if (reason instanceof Error) {
+			return reason;
+		}
+		if (typeof reason === "string") {
+			return new Error(reason);
+		}
+		return new Error(this.state.lastError ?? "Run aborted");
+	}
+
+	private async emit(event: AgentRuntimeEvent): Promise<void> {
+		const metadata = buildEventMetadata(event);
+		switch (event.type) {
+			case "run-started":
+				// Verbatim clinee calls `logger?.info?.(...)`. sdk-re's
+				// `BasicLogger` does not declare `info` (it uses `log`), so
+				// we narrow to an optional-info shape at the call site to
+				// preserve the clinee runtime contract without mutating
+				// shared's `BasicLogger` interface.
+				(
+					this.config.logger as
+						| {
+								info?: (msg: string, md?: unknown) => void;
+						  }
+						| undefined
+				)?.info?.("Agent run started", metadata);
+				break;
+			case "tool-finished":
+				(
+					this.config.logger as
+						| {
+								info?: (msg: string, md?: unknown) => void;
+						  }
+						| undefined
+				)?.info?.("Agent tool finished", metadata);
+				break;
+			case "run-failed":
+				this.config.logger?.error?.("Agent run failed", {
+					...metadata,
+					error: event.error,
+				});
+				captureSdkError(this.config.telemetry, {
+					component: "agents",
+					operation: "agent.run",
+					error: event.error,
+					severity: "error",
+					handled: false,
+					context: metadata as TelemetryProperties,
+				});
+				break;
+			default:
+				this.config.logger?.debug?.("Agent event", metadata);
+				break;
+		}
+		this.config.telemetry?.capture({
+			event: `agent.${event.type}`,
+			properties: metadata as TelemetryProperties,
+		});
+		for (const listener of this.listeners) {
+			listener(event);
+		}
+		for (const hook of this.hooks.onEvent) {
+			await hook(event);
+		}
+	}
+
+	private applyStopControl(
+		control: AgentStopControl | undefined | undefined,
+	): void {
+		if (!control?.stop) {
+			return;
+		}
+		if (control.reason) {
+			this.state.lastError = control.reason;
+		}
+		throw new ControlledStopError(control.reason);
+	}
+}
+
+function buildEventMetadata(event: AgentRuntimeEvent): Record<string, unknown> {
+	return {
+		agentId: event.snapshot.agentId,
+		agentRole: event.snapshot.agentRole,
+		runId: event.snapshot.runId,
+		status: event.snapshot.status,
+		iteration: event.snapshot.iteration,
+		eventType: event.type,
+	};
+}
+
+function mergeToolMetadata(current: unknown, patch: unknown): unknown {
+	if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+		return patch;
+	}
+	if (!current || typeof current !== "object" || Array.isArray(current)) {
+		return patch;
+	}
+	return {
+		...(current as Record<string, unknown>),
+		...patch,
+	};
+}
+
+function parseToolInput(assembly: PendingToolAssembly): {
+	input: unknown;
+	parseError?: string;
+	invalidInput: Record<string, unknown>;
+	reason?: InvalidToolCall["reason"];
+} {
+	if (assembly.inputValue !== undefined) {
+		return {
+			input: assembly.inputValue,
+			invalidInput: buildInvalidToolInput(JSON.stringify(assembly.inputValue)),
+		};
+	}
+	if (!assembly.inputText.trim()) {
+		return {
+			input: {},
+			invalidInput: {},
+		};
+	}
+	const parsed = parseToolArguments(assembly.inputText);
+	if (parsed.ok) {
+		return {
+			input: parsed.value,
+			invalidInput: buildInvalidToolInput(assembly.inputText),
+		};
+	}
+	return {
+		input: {},
+		invalidInput: buildInvalidToolInput(assembly.inputText, parsed.error),
+		parseError: `Tool call ${assembly.toolName ?? assembly.toolCallId} emitted invalid JSON arguments: ${parsed.error}`,
+		reason: "invalid_arguments",
+	};
+}
+
+function buildInvalidToolInput(
+	value: string,
+	parseError?: string,
+): Record<string, unknown> {
+	const trimmed = value.trim();
+	if (!trimmed) {
+		return {};
+	}
+	return parseError
+		? { rawInputText: value, parseError }
+		: { rawInputText: value };
+}
+
+function parseToolArguments(
+	value: string,
+): { ok: true; value: unknown } | { ok: false; error: string } {
+	const trimmed = value.trim();
+	if (!trimmed) {
+		return {
+			ok: false,
+			error: "Tool call arguments were empty.",
+		};
+	}
+
+	try {
+		return { ok: true, value: JSON.parse(trimmed) };
+	} catch {
+		// Fall through to a normalized error below.
+	}
+
+	if (!(trimmed.startsWith("{") || trimmed.startsWith("["))) {
+		return {
+			ok: false,
+			error: "Tool call arguments must be encoded as a JSON object or array.",
+		};
+	}
+
+	return {
+		ok: false,
+		error:
+			"Tool call arguments could not be parsed as JSON. Ensure the outer tool payload is valid JSON and escape embedded quotes/newlines inside string fields.",
+	};
+}
+
+function mergeToolInputText(current: string, incoming: string): string {
+	if (!current) {
+		return incoming;
+	}
+	const trimmed = incoming.trimStart();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		return incoming;
+	}
+	return current + incoming;
+}
+
+export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
+	return new AgentRuntime(config);
+}
+
+/**
+ * `Agent` is the user-friendly name for `AgentRuntime`. They are the same
+ * class; this alias exists so standalone callers can write:
+ *
+ *     const agent = new Agent({ providerId, modelId, apiKey });
+ *     await agent.run("hello");
+ *
+ * while `@cline/core` (which owns model construction) continues to use
+ * the `AgentRuntime` name with `{ model, ... }` configs.
+ */
+export const Agent = AgentRuntime;
+export type Agent = AgentRuntime;
+
+export function createAgent(config: AgentRuntimeConfig): AgentRuntime {
+	return new AgentRuntime(config);
+}