@clinebot/core 0.0.35 → 0.0.37

package/src/runtime/session-runtime-orchestrator.ts

@@ -0,0 +1,1253 @@
+/**
+ * Per-session `SessionRuntime` orchestrator (PLAN.md §3.2.3).
+ *
+ * Owns all cross-turn state for one logical agent session:
+ *
+ *   - `ConversationStore`      — message transcript + session-started gate
+ *   - `MistakeTracker`         — per-session consecutive-mistake counter
+ *   - `LoopDetectionTracker`   — per-session repeated-tool-call detector
+ *   - `MessageBuilder`         — provider-message assembly cache
+ *   - `HookEngine` + `HookBridge` — legacy `AgentHooks`/`AgentExtension[]`
+ *                                   → runtime-hook synthesis
+ *   - `RuntimeEventAdapter`    — per-run stateful `AgentRuntimeEvent`
+ *                                → legacy `AgentEvent` translator
+ *   - listener registry        — host subscribers see legacy `AgentEvent`s
+ *   - pending tool set, abort  — per-run lifecycle housekeeping
+ *
+ * A fresh `AgentRuntime` is instantiated per run via
+ * `createAgentRuntime(createAgentRuntimeConfig({...}))`; it is the
+ * only class that depends on `@clinebot/agents`. All session-level
+ * state outlives any one `AgentRuntime`, making OAuth-retry + run
+ * replay feasible (§3.2.2 invariant #3).
+ *
+ * NOTE: this class lives alongside the pre-existing
+ * `packages/core/src/runtime/session-runtime.ts`, which exports
+ * transport-level `SessionRuntime`/`RuntimeBuilder` interfaces
+ * consumed by `LocalRuntimeHost`. Both coexist through Step 8/9; the
+ * transport-level interface is retired in Step 10 (§3.6 Step 10).
+ *
+ * @see PLAN.md §3.2.3 — public surface.
+ * @see PLAN.md §3.2.2 — call graph and invariants.
+ * @see PLAN.md §3.6 Step 8d — landing commit.
+ */
+
+import type { AgentRuntime } from "@clinebot/agents";
+import { createAgentRuntime } from "@clinebot/agents";
+import {
+	type AgentConfig,
+	type AgentEvent,
+	type AgentExtension,
+	type AgentExtensionRegistry,
+	type AgentFinishReason,
+	type AgentResult,
+	type AgentRunResult,
+	type AgentRuntimeEvent,
+	type BasicLogger,
+	type ContributionRegistry,
+	createContributionRegistry,
+	HookEngine,
+	type ITelemetryService,
+	type LegacyAgentUsage,
+	type LoopDetectionConfig,
+	type Message,
+	type MessageWithMetadata,
+	type ModelInfo,
+	type Tool,
+	type ToolCallRecord,
+} from "@clinebot/shared";
+import { HookBridge } from "../hooks/hook-bridge";
+import {
+	createHandlerFromConfig,
+	resolveKnownModelsFromConfig,
+} from "../llms/handler-factory";
+import { ConversationStore } from "../session/conversation-store";
+import { MessageBuilder } from "../session/message-builder";
+import {
+	agentMessagesToMessagesWithMetadata,
+	apiHandlerToAgentModel,
+	messagesToAgentMessages,
+	toolsToAgentTools,
+} from "./agent-config-adapter";
+import { createAgentRuntimeConfig } from "./agent-runtime-config-builder";
+import { LoopDetectionTracker } from "./loop-detection";
+import { MistakeTracker } from "./mistake-tracker";
+import { RuntimeEventAdapter } from "./runtime-event-adapter";
+
+function formatToolResultError(output: unknown): string {
+	if (typeof output === "string") {
+		return output;
+	}
+	if (output instanceof Error) {
+		return output.message;
+	}
+	try {
+		return JSON.stringify(output);
+	} catch {
+		return String(output);
+	}
+}
+
+// =============================================================================
+// Public types
+// =============================================================================
+
+/**
+ * Listener invoked for every legacy `AgentEvent` produced by the
+ * session runtime. Use `subscribeEvents(listener)` — it returns an
+ * `unsubscribe` function.
+ */
+export type SessionEventListener = (event: AgentEvent) => void;
+
+/** Subset of host-side deps needed by the session orchestrator. */
+export interface SessionRuntimeOrchestratorDeps {
+	readonly logger?: BasicLogger;
+	readonly telemetry?: ITelemetryService;
+	/** Optional pre-constructed `HookEngine`. A fresh one is built when omitted. */
+	readonly hookEngine?: HookEngine;
+	/**
+	 * Test hook: override the `AgentRuntime` factory. Production
+	 * callers leave this undefined and get the real `createAgentRuntime`.
+	 */
+	readonly createAgentRuntimeImpl?: (
+		config: Parameters<typeof createAgentRuntime>[0],
+	) => AgentRuntime;
+}
+
+/** Connection overrides applied via `updateConnection`. */
+export interface ConnectionOverrides {
+	providerId?: string;
+	modelId?: string;
+	apiKey?: string;
+	baseUrl?: string;
+	headers?: Record<string, string>;
+	providerConfig?: unknown;
+	reasoningEffort?: AgentConfig["reasoningEffort"];
+	thinking?: boolean;
+	thinkingBudgetTokens?: number;
+}
+
+// =============================================================================
+// SessionRuntime orchestrator
+// =============================================================================
+
+/**
+ * Per-session orchestrator. Construct once per agent session; call
+ * `run` / `continue` repeatedly. The class matches the subset of
+ * legacy `Agent` surface that `legacy-agent-facade` needs in Step 8e.
+ *
+ * Named `SessionRuntime` to match PLAN.md §3.2.3. To avoid a symbol
+ * collision with the pre-existing transport-level `SessionRuntime`
+ * interface in `session-runtime.ts`, this file is **not** re-exported
+ * from `runtime/index.ts` or `src/index.ts`. Consumers (facade in
+ * Step 8e) import directly from this module.
+ */
+export class SessionRuntime {
+	private config: AgentConfig;
+	private readonly agentId: string;
+	private readonly parentAgentId?: string;
+	private readonly logger?: BasicLogger;
+	// Reserved for §3.4.4 telemetry parity (not yet consumed — §3.4.4
+	// listed as explicitly deferred until telemetry wiring is added).
+	// Typed as `readonly` to preserve the field slot for future use
+	// without re-touching the constructor.
+	readonly telemetry?: ITelemetryService;
+	private readonly hookEngine: HookEngine;
+	private readonly hookBridge: HookBridge;
+	private readonly conversation: ConversationStore;
+	private readonly mistakeTracker: MistakeTracker;
+	private readonly loopTracker: LoopDetectionTracker;
+	/**
+	 * True when `execution.loopDetection === false` at construction
+	 * time. Loop inspection is skipped entirely — the tracker still
+	 * exists for API compatibility but is never fed.
+	 */
+	private readonly loopDetectionDisabled: boolean;
+	// Reserved for host-owned message assembly (currently handled
+	// inline by `agentMessagesToMessages` in the adapter). Kept as a
+	// ready slot so the compaction plugin can install a beforeModel
+	// hook that feeds an explicit `MessageBuilder` later.
+	readonly messageBuilder: MessageBuilder;
+	/**
+	 * Contribution registry that hosts extension-provided tools,
+	 * commands, message builders, and providers. Lazily initialized
+	 * on first run (parity with legacy `Agent.ensureExtensionsInitialized`
+	 * at `packages/agents/src/agent.ts:1122-1147`).
+	 */
+	private readonly contributionRegistry: ContributionRegistry<
+		AgentExtension,
+		Tool,
+		Message[]
+	>;
+	private extensionsInitialized = false;
+	private readonly listeners = new Set<SessionEventListener>();
+	private readonly createAgentRuntimeImpl: (
+		config: Parameters<typeof createAgentRuntime>[0],
+	) => AgentRuntime;
+
+	/** Stable run id shared with the HookBridge during an active run. */
+	private activeRunId: string | null = null;
+	/** True while a run is in flight. `canStartRun()` is the negation. */
+	private running = false;
+	/** True once `abort()` has been requested for the active run. */
+	private abortRequested = false;
+	/** Last abort reason requested for the active run. */
+	private abortReason: string | undefined;
+	/** Reference to the current run's `AgentRuntime` so `abort` can forward. */
+	private activeRuntime: AgentRuntime | null = null;
+	/** Promise for the current run so shutdown can await an aborted run's drain. */
+	private activeRunPromise: Promise<AgentResult> | null = null;
+	/** Per-run `Agent → AgentEvent` adapter; `reset()` each run. */
+	private readonly eventAdapter = new RuntimeEventAdapter();
+	/** Session-shutdown gate — rejects late runs. */
+	private shutdownCalled = false;
+	/** Running tally of tool-call records for `AgentResult.toolCalls`. */
+	private currentRunToolCalls: ToolCallRecord[] = [];
+	/** Aggregated usage across the current run. */
+	private currentRunUsage: LegacyAgentUsage = {
+		inputTokens: 0,
+		outputTokens: 0,
+	};
+	/** Tool-start timestamps for `ToolCallRecord.durationMs`. */
+	private toolStartedAt = new Map<string, Date>();
+	/** Tool-call input snapshot for `ToolCallRecord.input`. */
+	private toolInputs = new Map<string, unknown>();
+	/**
+	 * Per-turn tool outcome counters used by the MistakeTracker wiring.
+	 * Reset on every `turn-started` event; consumed on `turn-finished`
+	 * to feed `mistakeTracker.record` when every tool call erred and no
+	 * successful call landed. Matches legacy `agent.ts` tool-failure
+	 * mistake-feed path (§3.4.6 + pre-Step-9 oracle lines 972-997).
+	 */
+	private currentTurnSuccessfulTools = 0;
+	private currentTurnFailedTools = 0;
+	private currentTurnFailureDetails: string[] = [];
+	/**
+	 * Serial queue for `MistakeTracker.record(...)` + loop-detection
+	 * side-effects fired from the sync `handleRuntimeEvent` stream. The
+	 * tracker's `record()` is async but the runtime event stream is
+	 * synchronous, so we chain tracker work onto a promise and await it
+	 * in `executeRun` before returning the `AgentResult`.
+	 */
+	private activeTrackerWork: Promise<void> = Promise.resolve();
+	/** True when tracker logic has issued an abort for the active run. */
+	private trackerAbortInFlight = false;
+
+	constructor(config: AgentConfig, deps: SessionRuntimeOrchestratorDeps = {}) {
+		this.config = config;
+		this.agentId = `agent_${Date.now()}_${Math.random()
+			.toString(36)
+			.slice(2, 8)}`;
+		this.parentAgentId = config.parentAgentId;
+		this.logger = deps.logger ?? config.logger;
+		this.telemetry = deps.telemetry ?? config.telemetry;
+		this.hookEngine = deps.hookEngine ?? new HookEngine();
+		this.createAgentRuntimeImpl =
+			deps.createAgentRuntimeImpl ?? createAgentRuntime;
+
+		this.conversation = new ConversationStore(config.initialMessages);
+		this.messageBuilder = new MessageBuilder();
+		this.contributionRegistry = createContributionRegistry<
+			AgentExtension,
+			Tool,
+			Message[]
+		>({
+			extensions: config.extensions ? [...config.extensions] : [],
+			setupContext: {
+				session: config.extensionContext?.session,
+				client: config.extensionContext?.client,
+				user: config.extensionContext?.user,
+				workspaceInfo: config.extensionContext?.workspace,
+				automation: config.extensionContext?.automation,
+				logger: config.extensionContext?.logger ?? this.logger,
+				telemetry: config.extensionContext?.telemetry ?? this.telemetry,
+			},
+		});
+		// Resolve + validate eagerly so `getExtensionRegistry()` is
+		// callable before the first run (legacy parity with
+		// `Agent` constructor at packages/agents/src/agent.ts:158-159).
+		// `setup()` is deferred to `ensureExtensionsInitialized` on
+		// the first run so async extension setup can't block the
+		// constructor.
+		this.contributionRegistry.resolve();
+		this.contributionRegistry.validate();
+		this.hookBridge = new HookBridge({
+			agentId: this.agentId,
+			conversationId: this.conversation.getConversationId(),
+			parentAgentId: this.parentAgentId ?? null,
+			hookEngine: this.hookEngine,
+			hooks: config.hooks,
+			extensions: config.extensions,
+			getRunId: () => this.activeRunId ?? "",
+			onHookContext: (_source, context) => {
+				// Legacy behaviour: hook-returned context becomes a user
+				// message on the next turn. Stash it on the conversation
+				// store so subsequent turns pick it up.
+				this.conversation.appendMessage({
+					role: "user",
+					content: [{ type: "text", text: context }],
+				});
+			},
+			onDispatchError: (error) => {
+				this.logger?.error?.("SessionRuntime hook dispatch failed", {
+					agentId: this.agentId,
+					error,
+				});
+			},
+		});
+
+		const maxMistakes = config.execution?.maxConsecutiveMistakes ?? 6;
+		this.mistakeTracker = new MistakeTracker({
+			maxConsecutiveMistakes: maxMistakes,
+			onLimitReached: config.onConsecutiveMistakeLimitReached,
+			emit: (event) => this.emitLegacyEvent(event),
+			log: (level, message, metadata) =>
+				leveledLog(this.logger, level, message, metadata),
+			agentId: this.agentId,
+			getConversationId: () => this.conversation.getConversationId(),
+			getActiveRunId: () => this.activeRunId ?? "",
+			appendRecoveryNotice: (message, _reason) => {
+				this.conversation.appendMessage({
+					role: "user",
+					content: [{ type: "text", text: message }],
+				});
+			},
+		});
+		const loopDetectionInput = config.execution?.loopDetection;
+		this.loopDetectionDisabled = loopDetectionInput === false;
+		const loopConfig: Partial<LoopDetectionConfig> | undefined =
+			loopDetectionInput === false || loopDetectionInput === undefined
+				? undefined
+				: loopDetectionInput;
+		this.loopTracker = new LoopDetectionTracker(loopConfig);
+	}
+
+	// -------------------------------------------------------------------
+	// Accessors & state mutators
+	// -------------------------------------------------------------------
+
+	getAgentId(): string {
+		return this.agentId;
+	}
+
+	getConversationId(): string {
+		return this.conversation.getConversationId();
+	}
+
+	getMessages(): MessageWithMetadata[] {
+		return this.conversation.getMessages();
+	}
+
+	/** True when no run is currently active and the session is not shut down. */
+	canStartRun(): boolean {
+		return !this.running && !this.shutdownCalled;
+	}
+
+	/**
+	 * Snapshot of the contribution registry (tools, commands, and other
+	 * extension contributions).
+	 *
+	 * Before the first run, the registry is in the `validate` phase:
+	 * extensions are validated but their `setup()` callbacks have not
+	 * run yet, so the snapshot only reflects eagerly-declared
+	 * contributions. After the first `run()`/`continue()`, the
+	 * registry is initialized (§`ensureExtensionsInitialized`), and
+	 * the snapshot reflects everything extensions registered via
+	 * `api.registerTool` / `registerCommand` / `registerMessageBuilder`
+	 * / `registerProvider` / `registerAutomationEventType`.
+	 */
+	getExtensionRegistry(): AgentExtensionRegistry<Tool, Message[]> {
+		return this.contributionRegistry.getRegistrySnapshot();
+	}
+
+	/** Append additional tools to every subsequent turn's runtime config. */
+	addTools(tools: Tool[]): void {
+		if (tools.length === 0) {
+			return;
+		}
+		const existing = new Set(this.config.tools.map((tool) => tool.name));
+		const merged = [...this.config.tools];
+		for (const tool of tools) {
+			if (!existing.has(tool.name)) {
+				merged.push(tool);
+				existing.add(tool.name);
+			}
+		}
+		this.config = { ...this.config, tools: merged };
+	}
+
+	/** Mutate provider / reasoning fields for subsequent runs. */
+	updateConnection(overrides: ConnectionOverrides): void {
+		const next: AgentConfig = { ...this.config };
+		if (overrides.providerId !== undefined)
+			next.providerId = overrides.providerId;
+		if (overrides.modelId !== undefined) next.modelId = overrides.modelId;
+		if (overrides.apiKey !== undefined) next.apiKey = overrides.apiKey;
+		if (overrides.baseUrl !== undefined) next.baseUrl = overrides.baseUrl;
+		if (overrides.headers !== undefined) next.headers = overrides.headers;
+		if (overrides.providerConfig !== undefined)
+			next.providerConfig = overrides.providerConfig;
+		if (overrides.reasoningEffort !== undefined)
+			next.reasoningEffort = overrides.reasoningEffort;
+		if (overrides.thinking !== undefined) next.thinking = overrides.thinking;
+		if (overrides.thinkingBudgetTokens !== undefined)
+			next.thinkingBudgetTokens = overrides.thinkingBudgetTokens;
+		this.config = next;
+	}
+
+	clearHistory(): void {
+		this.conversation.clearHistory();
+		this.resetConversationBoundaryTrackers();
+	}
+
+	restore(messages: readonly MessageWithMetadata[]): void {
+		this.conversation.restore(messages);
+		this.resetConversationBoundaryTrackers();
+	}
+
+	private resetConversationBoundaryTrackers(): void {
+		this.mistakeTracker.reset();
+		this.loopTracker.reset();
+	}
+
+	// -------------------------------------------------------------------
+	// Event subscription (legacy shape)
+	// -------------------------------------------------------------------
+
+	/**
+	 * Subscribe to **legacy** `AgentEvent`s. The session runtime
+	 * translates the new `AgentRuntimeEvent` stream via
+	 * `RuntimeEventAdapter` before fanout, so consumers see the
+	 * pre-swap shape.
+	 */
+	subscribeEvents(listener: SessionEventListener): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	// -------------------------------------------------------------------
+	// Abort / shutdown
+	// -------------------------------------------------------------------
+
+	abort(reason?: unknown): void {
+		const message =
+			typeof reason === "string"
+				? reason
+				: reason instanceof Error
+					? reason.message
+					: reason === undefined
+						? undefined
+						: String(reason);
+		this.abortRequested = true;
+		this.abortReason = message;
+		if (this.activeRunPromise) {
+			/**
+			 * Why this exists in hub mode:
+			 *
+			 * The TUI and the runtime are not always in the same process. In hub
+			 * mode, the visible TUI talks to a shared daemon over websocket. When the
+			 * user sends a prompt, the TUI sends a "start this run" command to the
+			 * daemon. The daemon starts the AgentRuntime and stores the promise for
+			 * that run as `activeRunPromise`.
+			 *
+			 * If the user presses Escape, the TUI sends a separate "cancel the
+			 * current run" command to the daemon. Cancelling a run means aborting the
+			 * AgentRuntime. That is supposed to interrupt the provider stream or any
+			 * other in-flight async work, and the normal way that interruption shows
+			 * up in JavaScript is a rejected promise. That rejection is not a bug by
+			 * itself. It is the expected result of the user saying "stop this
+			 * request."
+			 *
+			 * The important detail is that the rejection is already handled by the
+			 * code path that started the run. The original "start this run" command
+			 * is still awaiting `sessionHost.send(...)`, and that await is what
+			 * should eventually turn the run result or run error into a reply/event
+			 * for the client.
+			 *
+			 * The problem we hit was a timing gap inside the daemon process. The
+			 * separate cancel command can call `activeRuntime.abort(message)` while
+			 * the original start command is still waiting elsewhere. The abort can
+			 * make `activeRunPromise` reject immediately. If the runtime reports that
+			 * rejection before the original start command observes it, Node/Bun can
+			 * briefly classify it as an `unhandledRejection`.
+			 *
+			 * In the hub daemon, `unhandledRejection` is fatal. That is normally the
+			 * right policy because real unhandled errors should not be ignored. But
+			 * for this cancellation path it meant Escape could kill the daemon even
+			 * though the run error was expected and the original start command was
+			 * still responsible for handling it. After the daemon died, the next
+			 * prompt looked like it started loading, then silently stalled because
+			 * the TUI was talking to a dead runtime process.
+			 *
+			 * This `.catch()` is not the real application-level error handling. It is
+			 * only a local safety observer attached before we trigger the abort, so
+			 * the daemon does not mistake an expected cancellation rejection for a
+			 * process crash. We do not replace `activeRunPromise`, await this catch,
+			 * or convert the rejection into success. The original start command, and
+			 * any other caller awaiting `run()` / `continue()`, still receives the
+			 * same result or error it would have received without this observer.
+			 */
+			void this.activeRunPromise.catch(() => {});
+		}
+		this.activeRuntime?.abort(message);
+	}
+
+	/**
+	 * Shut the session down. Fires `hook.session_shutdown` exactly once
+	 * (legacy parity with `Agent.shutdown` at pre-Step-9 `agent.ts:325`)
+	 * and drains any in-flight async hooks through the hook engine.
+	 *
+	 * @param reason    Optional caller-supplied reason string (e.g.
+	 *                  `"session_complete"`, `"session_error"`,
+	 *                  `"session_stop"`, `"ctrl_d"`). Propagated into
+	 *                  the `session_shutdown` hook payload as
+	 *                  `AgentHookSessionShutdownContext.reason` so hook
+	 *                  handlers (e.g. hook-file runners) can route on
+	 *                  it — this matches the legacy `Agent.shutdown(reason)`
+	 *                  contract and keeps `isAbortReason(ctx.reason)`
+	 *                  checks in `hook-file-hooks.ts` working.
+	 * @param timeoutMs Optional drain timeout forwarded to
+	 *                  `HookEngine.shutdown`. Defaults to the engine's
+	 *                  own default (3000 ms) when omitted.
+	 */
+	async shutdown(reason?: string, timeoutMs?: number): Promise<void> {
+		if (this.running) {
+			if (!this.abortRequested || !this.activeRunPromise) {
+				throw new Error(
+					`SessionRuntime.shutdown called while a run is in progress (agentId=${this.agentId})`,
+				);
+			}
+			await this.activeRunPromise;
+		}
+		if (this.shutdownCalled) {
+			return;
+		}
+		this.shutdownCalled = true;
+		await this.hookBridge.dispatch("hook.session_shutdown", {
+			stage: "session_shutdown",
+			payload: {
+				agentId: this.agentId,
+				conversationId: this.conversation.getConversationId(),
+				sessionId: this.config.sessionId,
+				parentAgentId: this.parentAgentId ?? null,
+				reason,
+			},
+		});
+		await this.hookBridge.shutdown(timeoutMs);
+	}
+
+	// -------------------------------------------------------------------
+	// Run / continue
+	// -------------------------------------------------------------------
+
+	async run(
+		userMessage: string,
+		userImages?: string[],
+		userFiles?: string[],
+	): Promise<AgentResult> {
+		this.conversation.resetForRun();
+		this.resetConversationBoundaryTrackers();
+		return this.executeRun({
+			userMessage,
+			userImages,
+			userFiles,
+			isContinue: false,
+		});
+	}
+
+	async continue(
+		userMessage?: string,
+		userImages?: string[],
+		userFiles?: string[],
+	): Promise<AgentResult> {
+		return this.executeRun({
+			userMessage,
+			userImages,
+			userFiles,
+			isContinue: true,
+		});
+	}
+
+	// -------------------------------------------------------------------
+	// Private implementation
+	// -------------------------------------------------------------------
+
+	private async executeRun(input: {
+		userMessage?: string;
+		userImages?: string[];
+		userFiles?: string[];
+		isContinue: boolean;
+	}): Promise<AgentResult> {
+		const runPromise = this.executeRunInternal(input);
+		this.activeRunPromise = runPromise;
+		try {
+			return await runPromise;
+		} finally {
+			if (this.activeRunPromise === runPromise) {
+				this.activeRunPromise = null;
+			}
+		}
+	}
+
+	private async executeRunInternal(input: {
+		userMessage?: string;
+		userImages?: string[];
+		userFiles?: string[];
+		isContinue: boolean;
+	}): Promise<AgentResult> {
+		if (this.shutdownCalled) {
+			throw new Error(
+				`SessionRuntime.run called after shutdown (agentId=${this.agentId})`,
+			);
+		}
+		if (this.running) {
+			throw new Error(
+				`SessionRuntime state is "running"; call canStartRun() first (agentId=${this.agentId})`,
+			);
+		}
+		this.running = true;
+		this.abortRequested = false;
+		this.abortReason = undefined;
+		this.activeRunId = `run_${Date.now()}_${Math.random()
+			.toString(36)
+			.slice(2, 8)}`;
+		// Lazily initialize contribution-registry extensions on the
+		// first run. Legacy parity with `Agent.ensureExtensionsInitialized`
+		// (pre-Step-9 `agent.ts:245`/:277), called before any
+		// session_start / input / run_start dispatch.
+		await this.ensureExtensionsInitialized();
+		this.eventAdapter.reset();
+		this.currentRunToolCalls = [];
+		this.currentRunUsage = { inputTokens: 0, outputTokens: 0 };
+		this.toolStartedAt.clear();
+		this.toolInputs.clear();
+		this.currentTurnSuccessfulTools = 0;
+		this.currentTurnFailedTools = 0;
+		this.currentTurnFailureDetails = [];
+		this.activeTrackerWork = Promise.resolve();
+		this.trackerAbortInFlight = false;
+
+		const startedAt = new Date();
+		const mode: "run" | "continue" = input.isContinue ? "continue" : "run";
+
+		// ------------------------------------------------------------------
+		// session_start — dispatched once per logical session, before any
+		// run-scoped work. Parity with legacy agent.ts pre-Step-9 (L503).
+		// ConversationStore owns the "started" gate and resets it on
+		// resetForRun()/clearHistory()/restore() — i.e. a fresh session
+		// boundary refires session_start, matching legacy semantics.
+		// ------------------------------------------------------------------
+		if (!this.conversation.isSessionStarted()) {
+			const sessionStartControl = await this.hookBridge.dispatch(
+				"hook.session_start",
+				{
+					stage: "session_start",
+					payload: {
+						agentId: this.agentId,
+						conversationId: this.conversation.getConversationId(),
+						parentAgentId: this.parentAgentId ?? null,
+					},
+				},
+			);
+			this.conversation.markSessionStarted();
+			if (sessionStartControl?.cancel === true) {
+				return this.finalizeAbortedRun(startedAt);
+			}
+		}
+
+		// ------------------------------------------------------------------
+		// hook.input — dispatched once per run/continue when the caller
+		// supplied a user message. Honors control.overrideInput (string)
+		// and control.cancel. Parity with legacy agent.ts pre-Step-9
+		// (L1154 `prepareUserInput`).
+		// ------------------------------------------------------------------
+		let effectiveUserMessage = input.userMessage;
+		if (effectiveUserMessage !== undefined) {
+			const inputControl = await this.hookBridge.dispatch("hook.input", {
+				stage: "input",
+				payload: {
+					agentId: this.agentId,
+					conversationId: this.conversation.getConversationId(),
+					parentAgentId: this.parentAgentId ?? null,
+					mode,
+					input: effectiveUserMessage,
+				},
+			});
+			if (inputControl?.cancel === true) {
+				return this.finalizeAbortedRun(startedAt);
+			}
+			if (typeof inputControl?.overrideInput === "string") {
+				effectiveUserMessage = inputControl.overrideInput;
+			}
+		}
+
+		// Append the user turn (if any) to the conversation store. This
+		// must happen BEFORE we snapshot `initialMessages` below so the
+		// runtime sees the user message as part of its seed — we then
+		// pass an empty input to `runtime.run()` so the runtime does not
+		// append the message a second time (AgentRuntime.execute treats
+		// a falsy input as "no additional messages", per
+		// packages/agents/src/agent-runtime.ts normalizeInput path).
+		if (effectiveUserMessage !== undefined) {
+			const content = await buildUserTurnContent(
+				effectiveUserMessage,
+				input.userImages,
+				input.userFiles,
+				this.config.userFileContentLoader,
+			);
+			this.conversation.appendMessage({ role: "user", content });
+		}
+
+		// Build the AgentRuntime for this turn.
+		const handler = createHandlerFromConfig(this.config, this.logger);
+		const agentModel = apiHandlerToAgentModel(handler, {
+			prepareMessages: (messages) => this.prepareMessagesForApi(messages),
+		});
+		// Merge extension-contributed tools with the config-declared
+		// tools for this turn. Extensions register tools via
+		// `api.registerTool` during `setup()` — parity with legacy
+		// `Agent.ensureExtensionsInitialized` at pre-Step-9 `agent.ts:1140-1146`
+		// which merged `this.contributionRegistry.getRegisteredTools()`
+		// into `this.config.tools`. Dedupe by name so a config tool
+		// wins over a same-named extension tool (legacy behaviour:
+		// `validateTools` rejects duplicates; here we prefer the
+		// explicitly-declared config tool).
+		const extensionTools = this.contributionRegistry.getRegisteredTools();
+		const mergedToolsByName = new Map<string, Tool>();
+		for (const tool of extensionTools) {
+			mergedToolsByName.set(tool.name, tool);
+		}
+		for (const tool of this.config.tools) {
+			mergedToolsByName.set(tool.name, tool);
+		}
+		const conversationId = this.conversation.getConversationId();
+		const modelInfo = tryGetModelInfo(this.config);
+		const adaptedTools = toolsToAgentTools(
+			Array.from(mergedToolsByName.values()),
+			{
+				conversationId,
+				metadata: {
+					modelSupportsImages:
+						modelInfo?.capabilities?.includes("images") ?? true,
+					...this.config.toolContextMetadata,
+				},
+			},
+		);
+		// Seed initialMessages with the full prior transcript (including
+		// the user message we just appended) so multi-turn history is
+		// preserved across runs. Fixes P1 #1: prior turns were silently
+		// lost because `createAgentRuntimeConfig` received no seed and
+		// `replaceMessages(runResult.messages)` downstream overwrote the
+		// conversation with just the current-turn trail.
+		const initialMessages = messagesToAgentMessages(
+			this.conversation.getMessages(),
+		);
+		const runtimeConfig = createAgentRuntimeConfig({
+			agentConfig: this.config,
+			sessionId: this.config.sessionId,
+			agentId: this.agentId,
+			conversationId,
+			parentAgentId: this.parentAgentId,
+			model: agentModel,
+			logger: this.logger,
+			tools: adaptedTools,
+			hookBridge: this.hookBridge,
+			initialMessages,
+		});
+		const runtime = this.createAgentRuntimeImpl(runtimeConfig);
+		this.activeRuntime = runtime;
+		if (this.abortRequested) {
+			runtime.abort(this.abortReason);
+		}
+
+		// Subscribe to runtime events; fan out legacy events to listeners
+		// and keep private book-keeping for tool-call records / usage.
+		const unsubscribe = runtime.subscribe((event: AgentRuntimeEvent) => {
+			this.handleRuntimeEvent(event);
+		});
+
+		let runResult: AgentRunResult | undefined;
+		let thrownError: Error | undefined;
+		try {
+			// Pass empty input so AgentRuntime does not duplicate the
+			// user message we already seeded via `initialMessages`. The
+			// runtime's `normalizeInput` treats `""`/`undefined` as
+			// "no extra messages".
+			if (input.isContinue) {
+				runResult = await runtime.continue(undefined);
+			} else {
+				runResult = await runtime.run("");
+			}
+		} catch (error) {
+			thrownError = error instanceof Error ? error : new Error(String(error));
+		} finally {
+			unsubscribe();
+			// Drain any in-flight tracker work (mistake/loop side-effects
+			// queued from handleRuntimeEvent) before we clear state so a
+			// late abort can still reach the runtime if needed.
+			try {
+				await this.activeTrackerWork;
+			} catch (error) {
+				this.logger?.error?.(
+					"SessionRuntime tracker work failed during drain",
+					{ agentId: this.agentId, error },
+				);
+			}
+			this.activeRuntime = null;
+			this.running = false;
+			this.abortRequested = false;
+			this.abortReason = undefined;
+		}
+
+		// Persist the runtime's message trail back into the conversation
+		// store so later turns see assistant output. The runtime state
+		// was seeded with the full transcript, so `runResult.messages`
+		// IS the complete new transcript (seed + newly-produced turn).
+		if (runResult && runResult.messages.length > 0) {
+			const replacement = agentMessagesToMessagesWithMetadata(
+				runResult.messages,
+			);
+			this.conversation.replaceMessages(replacement);
+		}
+
+		const endedAt = new Date();
+		try {
+			const result = this.buildLegacyResult({
+				runResult,
+				thrownError,
+				startedAt,
+				endedAt,
+			});
+			await this.dispatchRunEnd(result);
+			return result;
+		} finally {
+			this.activeRunId = null;
+		}
+	}
+
+	/**
+	 * Build an aborted `AgentResult` without invoking the AgentRuntime.
+	 * Used by the `hook.session_start` / `hook.input` cancel paths —
+	 * legacy parity: a hook that returns `{ cancel: true }` short-circuits
+	 * the run and yields `finishReason: "aborted"`.
+	 */
+	private finalizeAbortedRun(startedAt: Date): AgentResult {
+		this.activeRuntime = null;
+		this.activeRunId = null;
+		this.running = false;
+		this.abortRequested = false;
+		this.abortReason = undefined;
+		const endedAt = new Date();
+		const messages = this.conversation.getMessages();
+		const modelInfo = tryGetModelInfo(this.config);
+		return {
+			text: "",
+			usage: { inputTokens: 0, outputTokens: 0 },
+			messages,
+			toolCalls: [],
+			iterations: 0,
+			finishReason: "aborted",
+			model: {
+				id: this.config.modelId,
+				provider: this.config.providerId,
+				info: modelInfo,
+			},
+			startedAt,
+			endedAt,
+			durationMs: endedAt.getTime() - startedAt.getTime(),
+		};
+	}
+
+	/**
+	 * Initialize the contribution registry once per session. Runs
+	 * extension `setup()` callbacks so they can `registerTool`,
+	 * `registerCommand`, `registerMessageBuilder`, and
+	 * `registerProvider`. Matches legacy `Agent.ensureExtensionsInitialized`
+	 * at pre-Step-9 `agent.ts:1122-1147`:
+	 *
+	 *   - on `hookErrorMode === "throw"`, setup failures propagate;
+	 *   - otherwise setup failures emit a recoverable `error` event
+	 *     via the legacy event channel and leave the registry
+	 *     partially initialized.
+	 *
+	 * Idempotent: subsequent calls are no-ops once the registry has
+	 * been activated.
+	 */
+	private async ensureExtensionsInitialized(): Promise<void> {
+		if (this.extensionsInitialized) {
+			return;
+		}
+		try {
+			await this.contributionRegistry.initialize();
+		} catch (error) {
+			if (this.config.hookErrorMode === "throw") {
+				throw error;
+			}
+			this.emitLegacyEvent({
+				type: "error",
+				error: error instanceof Error ? error : new Error(String(error)),
+				recoverable: true,
+				iteration: 0,
+			});
+		}
+		this.extensionsInitialized = true;
+	}
+
+	private async prepareMessagesForApi(messages: Message[]): Promise<Message[]> {
+		let prepared = messages;
+		for (const builder of this.contributionRegistry.getRegistrySnapshot()
+			.messageBuilder) {
+			prepared = await builder.build(prepared);
+		}
+		return this.messageBuilder.buildForApi(prepared);
+	}
+
+	private handleRuntimeEvent(event: AgentRuntimeEvent): void {
+		// Track tool-call records before translation so the timing data
+		// is available to observers via `AgentResult.toolCalls`.
+		switch (event.type) {
+			case "turn-started": {
+				// Reset per-turn tool-outcome counters used by the
+				// MistakeTracker wiring. Parity with pre-Step-9
+				// agent.ts which accumulates per-iteration success/fail
+				// counts and feeds them into recordMistake at the
+				// turn boundary.
+				this.currentTurnSuccessfulTools = 0;
+				this.currentTurnFailedTools = 0;
+				this.currentTurnFailureDetails = [];
+				break;
+			}
+			case "tool-started": {
+				this.toolStartedAt.set(event.toolCall.toolCallId, new Date());
+				this.toolInputs.set(event.toolCall.toolCallId, event.toolCall.input);
+				// Loop-detection inspection: identical consecutive
+				// tool-call signatures trip the tracker. On "soft"
+				// verdict we append a recovery notice; on "hard"
+				// verdict we feed the mistake tracker with
+				// forceAtLimit:true and abort. Parity with pre-Step-9
+				// agent.ts L917-954.
+				this.inspectLoopForToolCall(
+					event.toolCall.toolName,
+					event.toolCall.input,
+					event.iteration,
+				);
+				break;
+			}
+			case "tool-finished": {
+				const startedAt = this.toolStartedAt.get(event.toolCall.toolCallId);
+				const endedAt = new Date();
+				const input = this.toolInputs.get(event.toolCall.toolCallId);
+				this.toolStartedAt.delete(event.toolCall.toolCallId);
+				this.toolInputs.delete(event.toolCall.toolCallId);
+				const resultPart = event.message.content.find(
+					(part) => part.type === "tool-result",
+				);
+				const isError =
+					resultPart?.type === "tool-result" && resultPart.isError === true;
+				const errorText = isError
+					? formatToolResultError(
+							resultPart?.type === "tool-result"
+								? resultPart.output
+								: undefined,
+						)
+					: undefined;
+				const record: ToolCallRecord = {
+					id: event.toolCall.toolCallId,
+					name: event.toolCall.toolName,
+					input,
+					output:
+						resultPart?.type === "tool-result" ? resultPart.output : undefined,
+					error: errorText,
+					durationMs:
+						startedAt === undefined
+							? 0
+							: endedAt.getTime() - startedAt.getTime(),
+					startedAt: startedAt ?? endedAt,
+					endedAt,
+				};
+				this.currentRunToolCalls.push(record);
+				// Per-turn success/failure bookkeeping for MistakeTracker.
+				if (isError) {
+					this.currentTurnFailedTools += 1;
+					if (errorText) {
+						this.currentTurnFailureDetails.push(
+							`[${event.toolCall.toolName}] ${errorText}`,
+						);
+					}
+				} else {
+					this.currentTurnSuccessfulTools += 1;
+				}
+				break;
+			}
+			case "turn-finished": {
+				// End-of-turn mistake evaluation: legacy parity (pre-Step-9
+				// agent.ts L972-997). When some tool calls failed and the
+				// turn had no successful tool calls, record a mistake;
+				// reset on productive turns.
+				const failed = this.currentTurnFailedTools;
+				const succeeded = this.currentTurnSuccessfulTools;
+				if (failed > 0 && succeeded === 0) {
+					const details = this.currentTurnFailureDetails.join("; ");
+					this.enqueueMistakeRecord({
+						iteration: event.iteration,
+						reason: "tool_execution_failed",
+						details: `${failed} tool call(s) failed${
+							details ? `: ${details}` : ""
+						}`,
+					});
+				} else if (succeeded > 0) {
+					// Productive turn — reset the tracker so transient
+					// failures don't accumulate across unrelated turns.
+					this.mistakeTracker.reset();
+				}
+				break;
+			}
+			case "usage-updated": {
+				this.currentRunUsage = {
+					inputTokens: event.usage.inputTokens,
+					outputTokens: event.usage.outputTokens,
+					cacheReadTokens:
+						event.usage.cacheReadTokens > 0
+							? event.usage.cacheReadTokens
+							: undefined,
+					cacheWriteTokens:
+						event.usage.cacheWriteTokens > 0
+							? event.usage.cacheWriteTokens
+							: undefined,
+					totalCost: event.usage.totalCost,
+				};
+				break;
+			}
+			default:
+				break;
+		}
+		for (const legacy of this.eventAdapter.translate(event)) {
+			this.emitLegacyEvent(legacy);
+		}
+	}
+
+	private emitLegacyEvent(event: AgentEvent): void {
+		for (const listener of this.listeners) {
+			try {
+				listener(event);
+			} catch (error) {
+				this.logger?.error?.("SessionRuntime event listener threw", {
+					agentId: this.agentId,
+					error,
+				});
+			}
+		}
+	}
+
+	/**
+	 * Feed the `LoopDetectionTracker` with a tool-call and react to
+	 * the returned verdict. Parity with pre-Step-9 agent.ts L917-954:
+	 *
+	 *   - `"soft"`  → append a recovery notice telling the model to
+	 *                 change approach;
+	 *   - `"hard"`  → feed `MistakeTracker.record` with
+	 *                 `forceAtLimit:true`. When the tracker returns
+	 *                 `action: "stop"`, append the stop notice and
+	 *                 abort the active runtime.
+	 */
+	private inspectLoopForToolCall(
+		toolName: string,
+		input: unknown,
+		iteration: number,
+	): void {
+		if (this.trackerAbortInFlight || this.loopDetectionDisabled) {
+			return;
+		}
+		const verdict = this.loopTracker.inspect({ name: toolName, input });
+		if (verdict.kind === "ok") {
+			return;
+		}
+		if (verdict.kind === "soft") {
+			if (verdict.message) {
+				this.conversation.appendMessage({
+					role: "user",
+					content: [{ type: "text", text: verdict.message }],
+				});
+			}
+			return;
+		}
+		// Hard escalation.
+		this.enqueueMistakeRecord({
+			iteration,
+			reason: "tool_execution_failed",
+			forceAtLimit: true,
+			details:
+				verdict.message ??
+				`Detected repeated tool calls to \`${toolName}\`; stopping to avoid a loop.`,
+		});
+	}
+
+	/**
+	 * Enqueue a mistake-record onto the serial tracker work chain. The
+	 * runtime event stream is synchronous but `MistakeTracker.record`
+	 * is async — chaining onto a shared promise preserves ordering
+	 * (legacy parity) and lets `executeRun` await draining before
+	 * returning the `AgentResult`.
+	 *
+	 * When the tracker returns `action: "stop"`, append the stop notice
+	 * to the conversation and abort the active runtime so the run ends
+	 * with `finishReason: "aborted"`.
+	 */
+	private enqueueMistakeRecord(input: {
+		iteration: number;
+		reason: "api_error" | "invalid_tool_call" | "tool_execution_failed";
+		details?: string;
+		forceAtLimit?: boolean;
+	}): void {
+		if (this.trackerAbortInFlight) {
+			return;
+		}
+		this.activeTrackerWork = this.activeTrackerWork.then(async () => {
+			if (this.trackerAbortInFlight) {
+				return;
+			}
+			const outcome = await this.mistakeTracker.record(input);
+			if (outcome.action === "stop") {
+				this.trackerAbortInFlight = true;
+				this.conversation.appendMessage({
+					role: "user",
+					content: [{ type: "text", text: outcome.message }],
+				});
+				this.activeRuntime?.abort(outcome.reason ?? outcome.message);
+			}
+		});
+	}
+
+	private buildLegacyResult(input: {
+		runResult: AgentRunResult | undefined;
+		thrownError: Error | undefined;
+		startedAt: Date;
+		endedAt: Date;
+	}): AgentResult {
+		const { runResult, thrownError, startedAt, endedAt } = input;
+		const durationMs = endedAt.getTime() - startedAt.getTime();
+		const finishReason: AgentFinishReason = thrownError
+			? "error"
+			: deriveFinishReason(runResult);
+		const text =
+			runResult?.outputText ||
+			(runResult?.status === "failed" ? runResult.error?.message : undefined) ||
+			"";
+		const usage: LegacyAgentUsage = runResult
+			? {
+					inputTokens: runResult.usage.inputTokens,
+					outputTokens: runResult.usage.outputTokens,
+					cacheReadTokens:
+						runResult.usage.cacheReadTokens > 0
+							? runResult.usage.cacheReadTokens
+							: undefined,
+					cacheWriteTokens:
+						runResult.usage.cacheWriteTokens > 0
+							? runResult.usage.cacheWriteTokens
+							: undefined,
+					totalCost: runResult.usage.totalCost,
+				}
+			: this.currentRunUsage;
+		const messages = runResult
+			? agentMessagesToMessagesWithMetadata(runResult.messages)
+			: this.conversation.getMessages();
+		const modelInfo = tryGetModelInfo(this.config);
+		if (thrownError) {
+			throw thrownError;
+		}
+		return {
+			text,
+			usage,
+			messages,
+			toolCalls: this.currentRunToolCalls,
+			iterations: runResult?.iterations ?? 0,
+			finishReason,
+			model: {
+				id: this.config.modelId,
+				provider: this.config.providerId,
+				info: modelInfo,
+			},
+			startedAt,
+			endedAt,
+			durationMs,
+		};
+	}
+
+	private async dispatchRunEnd(result: AgentResult): Promise<void> {
+		await this.hookBridge.dispatch("hook.run_end", {
+			stage: "run_end",
+			iteration: result.iterations,
+			payload: {
+				agentId: this.agentId,
+				conversationId: this.conversation.getConversationId(),
+				parentAgentId: this.parentAgentId ?? null,
+				result,
+			},
+		});
+	}
+}
+
+// =============================================================================
+// Module-level helpers
+// =============================================================================
+
+function leveledLog(
+	logger: BasicLogger | undefined,
+	level: "debug" | "info" | "warn" | "error",
+	message: string,
+	metadata?: Record<string, unknown>,
+): void {
+	if (!logger) {
+		return;
+	}
+	if (level === "debug") {
+		logger.debug(message, metadata);
+		return;
+	}
+	if (level === "error" && logger.error) {
+		logger.error(message, metadata);
+		return;
+	}
+	const severity: "info" | "warn" | "error" =
+		level === "warn" ? "warn" : level === "error" ? "error" : "info";
+	logger.log(message, { ...metadata, severity });
+}
+
+function deriveFinishReason(
+	runResult: AgentRunResult | undefined,
+): AgentFinishReason {
+	if (!runResult) {
+		return "error";
+	}
+	switch (runResult.status) {
+		case "completed":
+			return "completed";
+		case "aborted":
+			return "aborted";
+		case "failed":
+			return "error";
+	}
+}
+
+async function buildUserTurnContent(
+	userMessage: string,
+	userImages: string[] | undefined,
+	userFiles: string[] | undefined,
+	loader: AgentConfig["userFileContentLoader"],
+): Promise<Message["content"]> {
+	// Import lazily to avoid a circular-import hazard via runtime barrels.
+	const { buildInitialUserContent } = await import("./user-input-builder");
+	return buildInitialUserContent(userMessage, userImages, userFiles, loader);
+}
+
+function tryGetModelInfo(config: AgentConfig): ModelInfo | undefined {
+	if (config.knownModels?.[config.modelId]) {
+		return config.knownModels[config.modelId];
+	}
+	const resolvedKnownModels = resolveKnownModelsFromConfig(config);
+	if (resolvedKnownModels?.[config.modelId]) {
+		return resolvedKnownModels[config.modelId];
+	}
+	return undefined;
+}