@dex-ai/sdk 0.1.30

package/src/generate.ts

@@ -0,0 +1,943 @@
+/**
+ * The generate loop — event-driven.
+ *
+ * Emits events to extensions via ext.on['event-name']. Extensions subscribe
+ * to events they care about. The loop orchestrates model calls, tool dispatch,
+ * and context injection purely through events.
+ */
+
+import type {
+	AgentContext,
+	AgentStream,
+	AgentStreamPart,
+	AnyTool,
+	Content,
+	ErrorSource,
+	Extension,
+	FinishReason,
+	GenerateContext,
+	GenerateOptions,
+	GenerateResult,
+	Message,
+	ModelRequest,
+	ToolCall,
+	ToolCallContent,
+	ToolResult,
+	Usage,
+} from "./index";
+import { mergeSignals, PushStream, formatError } from "./util";
+import { dispatchTool } from "./tool-dispatch";
+import {
+	TOOL_RESULT_CACHE_KEY,
+	type ResolvedCacheConfig,
+} from "./tool-result-cache";
+import { validateToolSchemas } from "./resolve-schema";
+
+const EMPTY_USAGE: Usage = { inputTokens: 0, outputTokens: 0 };
+const DEFAULT_TOOL_TIMEOUT_MS = 120_000; // 2 minutes
+
+/* ------------------------------------------------------------------ */
+/* Structured Error Logging                                            */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Format ErrorSource context for logging.
+ */
+function formatErrorSource(source: ErrorSource): string {
+	const parts = [`[error:${source.kind}]`];
+	if (source.extensionName) parts.push(`ext=${source.extensionName}`);
+	if (source.event) parts.push(`event=${source.event}`);
+	if (source.call) parts.push(`tool=${source.call.toolName}`);
+	return parts.join(" ");
+}
+
+function addUsage(a: Usage, b: Usage): Usage {
+	const total = (a.totalTokens ?? 0) + (b.totalTokens ?? 0);
+	const cached = (a.cachedInputTokens ?? 0) + (b.cachedInputTokens ?? 0);
+	const cacheCreation =
+		(a.cacheCreationInputTokens ?? 0) + (b.cacheCreationInputTokens ?? 0);
+	const reasoning = (a.reasoningTokens ?? 0) + (b.reasoningTokens ?? 0);
+	return {
+		inputTokens: a.inputTokens + b.inputTokens,
+		outputTokens: a.outputTokens + b.outputTokens,
+		...(total > 0 ? { totalTokens: total } : {}),
+		...(cached > 0 ? { cachedInputTokens: cached } : {}),
+		...(cacheCreation > 0 ? { cacheCreationInputTokens: cacheCreation } : {}),
+		...(reasoning > 0 ? { reasoningTokens: reasoning } : {}),
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Tool collection                                                     */
+/* ------------------------------------------------------------------ */
+
+/** Track tools already warned about to avoid spam on every generate(). */
+const _warnedTools = new Set<string>();
+
+function collectTools(
+	extensions: ReadonlyArray<Extension>,
+): Map<string, AnyTool> {
+	const byName = new Map<string, AnyTool>();
+	const toolSources = new Map<string, string>(); // tool name -> first extension name
+	for (const ext of extensions) {
+		const raw = ext.tools;
+		if (raw === undefined) continue;
+		const list: ReadonlyArray<AnyTool> = Array.isArray(raw)
+			? raw
+			: [raw as AnyTool];
+
+		// Validate tool schemas eagerly — exclude tools with fatal schema issues
+		const diagnostics = validateToolSchemas(list, { extensionName: ext.name });
+		const errorTools = new Set(
+			diagnostics.filter((d) => d.severity === "error").map((d) => d.toolName),
+		);
+
+		// Log diagnostics (only first time per tool)
+		for (const d of diagnostics) {
+			const key = `${ext.name}:${d.toolName}:${d.severity}`;
+			if (_warnedTools.has(key)) continue;
+			_warnedTools.add(key);
+			const prefix = d.severity === "error" ? "ERROR" : "WARN";
+			const src = d.extensionName ? ` [${d.extensionName}]` : "";
+			console.error(`[tool-schema:${prefix}] ${d.toolName}${src}: ${d.issue}`);
+		}
+
+		for (const tool of list) {
+			// Skip tools with schema errors — they would break the provider
+			if (errorTools.has(tool.name)) {
+				console.error(
+					`[tool-schema] Excluding tool "${tool.name}" from extension "${ext.name}" due to schema errors`,
+				);
+				continue;
+			}
+
+			if (byName.has(tool.name)) {
+				// Same extension name providing the same tool = duplicate extension instance, skip.
+				// Different extension providing same tool name = real conflict, throw.
+				const firstSource = toolSources.get(tool.name);
+				if (firstSource === ext.name) {
+					// Duplicate extension instance — skip silently
+					continue;
+				}
+				throw new Error(
+					`Duplicate tool name: ${tool.name} (from extension ${ext.name}, already registered by ${firstSource})`,
+				);
+			}
+			byName.set(tool.name, tool);
+			toolSources.set(tool.name, ext.name);
+		}
+	}
+	return byName;
+}
+
+/* ------------------------------------------------------------------ */
+/* Context collection                                                  */
+/* ------------------------------------------------------------------ */
+
+/** Collect context from extensions that return AsyncIterable<Content> for generate-start. */
+async function collectContext(
+	extensions: ReadonlyArray<Extension>,
+	gctx: GenerateContext,
+): Promise<Content[]> {
+	const content: Content[] = [];
+	for (const ext of extensions) {
+		const handler = ext.on?.["generate-start"];
+		if (!handler) continue;
+		try {
+			const result = await handler(gctx);
+			if (result && Symbol.asyncIterator in (result as object)) {
+				for await (const c of result as AsyncIterable<Content>) {
+					content.push(c);
+				}
+			}
+		} catch (err) {
+			console.warn(`[${ext.name}] generate-start context failed:`, err);
+		}
+	}
+	return content;
+}
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+function toAssistantMessage(content: ReadonlyArray<Content>): Message {
+	return { role: "assistant", content };
+}
+
+function commitMessage(
+	actx: AgentContext,
+	message: Message,
+	emit: (p: AgentStreamPart) => void,
+	generateId?: string,
+) {
+	const stamped: Message = generateId ? { ...message, generateId } : message;
+	actx.appendMessage(stamped);
+	const msg = actx.messages[actx.messages.length - 1]!;
+	emit({
+		type: "message-committed",
+		message: msg,
+		index: actx.messages.length - 1,
+	});
+}
+
+function newGenerateContext(
+	actx: AgentContext,
+	opts: GenerateOptions,
+	signal: AbortSignal,
+	generateId: string,
+): GenerateContext {
+	return {
+		agent: actx,
+		generateId,
+		content: [],
+		state: new Map(),
+		stepCount: 0,
+		maxSteps: opts.maxSteps ?? 10,
+		usage: { ...EMPTY_USAGE },
+		signal,
+	};
+}
+
+function buildRequest(
+	actx: AgentContext,
+	tools: ReadonlyArray<AnyTool>,
+	opts: GenerateOptions,
+	signal: AbortSignal,
+): ModelRequest {
+	return {
+		messages: actx.messages,
+		signal,
+		...(tools.length ? { tools } : {}),
+		...(opts.temperature !== undefined
+			? { temperature: opts.temperature }
+			: {}),
+		...(opts.topP !== undefined ? { topP: opts.topP } : {}),
+		...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+		...(opts.stopSequences !== undefined
+			? { stopSequences: opts.stopSequences }
+			: {}),
+		...(opts.seed !== undefined ? { seed: opts.seed } : {}),
+		...(opts.providerOptions !== undefined
+			? { providerOptions: opts.providerOptions }
+			: {}),
+		...(opts.thinking !== undefined ? { thinking: opts.thinking } : {}),
+	};
+}
+
+/**
+ * Compute cache breakpoint indices for providers with explicit prompt caching.
+ *
+ * Strategy:
+ * - Place a breakpoint on the last message before the "new" content for this step.
+ *   This ensures the stable prefix (everything before the latest additions) is cached.
+ * - On step 0: breakpoint at the second-to-last user turn boundary (history is stable).
+ * - On step N>0: breakpoint at the last user message (everything before latest
+ *   tool results is stable from the previous step).
+ *
+ * Respects a limit of 2 message breakpoints (Anthropic allows 4 total,
+ * but 1 is used for system and 1 for tools).
+ */
+function computeCacheBreakpoints(
+	messages: ReadonlyArray<Message>,
+	step: number,
+): number[] {
+	const breakpoints: number[] = [];
+
+	if (messages.length < 4) return breakpoints;
+
+	// Find user message boundaries (turn starts)
+	const userIndices: number[] = [];
+	for (let i = 0; i < messages.length; i++) {
+		if (messages[i]!.role === "user" && messages[i]!.type !== "context-turn") {
+			userIndices.push(i);
+		}
+	}
+
+	if (userIndices.length < 2) return breakpoints;
+
+	// Primary breakpoint: the second-to-last user message.
+	// Everything up to and including this message is stable:
+	// - On step 0: this is the previous turn (history boundary)
+	// - On step N: this is the current turn's user message (everything
+	//   before the latest assistant+tool-result is stable)
+	const secondToLast = userIndices[userIndices.length - 2]!;
+	breakpoints.push(secondToLast);
+
+	// For long conversations: add a breakpoint deeper in history
+	// to ensure the early prefix stays cached even as the conversation grows.
+	// Place it at roughly the 1/3 mark of the conversation.
+	if (userIndices.length >= 6) {
+		const earlyIdx = userIndices[Math.floor(userIndices.length / 3)]!;
+		if (earlyIdx > 0 && earlyIdx < secondToLast) {
+			breakpoints.unshift(earlyIdx);
+		}
+	}
+
+	// Limit to 2 breakpoints for messages (system + tools use the other 2)
+	return breakpoints.slice(0, 2);
+}
+
+/* ------------------------------------------------------------------ */
+/* Entry point                                                         */
+/* ------------------------------------------------------------------ */
+
+export function runGenerate(
+	actx: AgentContext,
+	opts: GenerateOptions,
+): AgentStream {
+	const stream = new PushStream<AgentStreamPart>();
+	let resolveResult: (r: GenerateResult) => void;
+	let rejectResult: (err: unknown) => void;
+	const resultPromise = new Promise<GenerateResult>((resolve, reject) => {
+		resolveResult = resolve;
+		rejectResult = reject;
+	});
+
+	queueMicrotask(() => {
+		loop(actx, opts, stream).then(resolveResult!, (err) => {
+			stream.fail(err);
+			rejectResult!(err);
+		});
+	});
+
+	return Object.assign(stream, { result: resultPromise }) as AgentStream;
+}
+
+/* ------------------------------------------------------------------ */
+/* The loop                                                            */
+/* ------------------------------------------------------------------ */
+
+async function loop(
+	actx: AgentContext,
+	opts: GenerateOptions,
+	stream: PushStream<AgentStreamPart>,
+): Promise<GenerateResult> {
+	const extensions = actx.extensions;
+	const tools = collectTools(extensions);
+	const toolList = Array.from(tools.values());
+	const generateId = crypto.randomUUID();
+	const emit = (p: AgentStreamPart) => stream.push(p);
+	const signals = mergeSignals(actx.signal, opts.signal);
+	const signal = signals.signal;
+	const gctx = newGenerateContext(actx, opts, signal, generateId);
+	const cacheConfig = actx.state.get(TOOL_RESULT_CACHE_KEY) as
+		| ResolvedCacheConfig
+		| undefined;
+
+	const reportError = async (err: unknown, source: ErrorSource) => {
+		// Always log structured error with stack trace for troubleshooting
+		const formatted = formatError(err);
+		const sourceCtx = formatErrorSource(source);
+		console.error(`${sourceCtx} ${formatted}`);
+
+		// Emit extension-info error part so TUI/headless can display it
+		try {
+			emit({
+				type: "extension-info",
+				extension: "generate-loop",
+				level: "error",
+				text: `${sourceCtx} ${err instanceof Error ? err.message : String(err)}`,
+			});
+		} catch {
+			/* stream may be closed */
+		}
+
+		for (const ext of extensions) {
+			const handler = ext.on?.["error"];
+			if (!handler) continue;
+			try {
+				await handler(err, source, gctx);
+			} catch (handlerErr) {
+				// Log but don't propagate — error handlers must not crash the loop
+				console.error(
+					`[error-handler:${ext.name}] handler threw: ${formatError(handlerErr)}`,
+				);
+			}
+		}
+	};
+
+	const toolResultMessages: Message[] = [];
+	let finalAssistant: Message | null = null;
+	let finishReason: FinishReason = "stop";
+	let generateStopFired = false;
+
+	signal.addEventListener(
+		"abort",
+		() => {
+			finishReason = "abort";
+			emit({ type: "abort", reason: signal.reason });
+		},
+		{ once: true },
+	);
+
+	try {
+		// 1. Fire generate-input — let extensions augment input messages.
+		const inputMessages = [...opts.input] as Message[];
+		for (const ext of extensions) {
+			const handler = ext.on?.["generate-input"];
+			if (!handler) continue;
+			try {
+				const extra = await handler(inputMessages, gctx);
+				if (extra && extra.length > 0) {
+					// Append to the last user message's content
+					let lastUserIdx = -1;
+					for (let i = inputMessages.length - 1; i >= 0; i--) {
+						if (inputMessages[i]!.role === "user") {
+							lastUserIdx = i;
+							break;
+						}
+					}
+					if (lastUserIdx >= 0) {
+						const msg = inputMessages[lastUserIdx]!;
+						inputMessages[lastUserIdx] = {
+							...msg,
+							content: [...msg.content, ...extra],
+						};
+					}
+				}
+			} catch (err) {
+				await reportError(err, {
+					kind: "extension",
+					extensionName: ext.name,
+					event: "generate-input",
+				});
+			}
+		}
+
+		// 2. Append input messages (stamped with generateId for turn tracking).
+		for (const m of inputMessages) {
+			const stamped: Message = { ...m, generateId };
+			actx.appendMessage(stamped);
+			emit({
+				type: "message-committed",
+				message: stamped,
+				index: actx.messages.length - 1,
+			});
+		}
+
+		// 2. emit('generate-start') — collect ephemeral context.
+		emit({
+			type: "generate-start",
+			maxSteps: gctx.maxSteps,
+			startedAt: Date.now(),
+			generateId,
+		});
+		const turnContext = await collectContext(extensions, gctx);
+
+		// Build an ephemeral context message that is injected into each model
+		// request but never committed to actx.messages or persisted to session.
+		// This mirrors cache_control: ephemeral semantics — the model sees it
+		// on the current turn but it does not pollute history on resume.
+		const ephemeralCtxMsg: Message | null =
+			turnContext.length > 0
+				? { role: "user", content: [...turnContext], type: "context-turn" }
+				: null;
+
+		// 3. Iteration loop.
+		let step = 0;
+		let lastIterUsage: Usage = { ...EMPTY_USAGE };
+		(gctx as { stepCount: number }).stepCount = step;
+
+		while (true) {
+			if (signal.aborted) break;
+
+			// 3a. emit('model-start') — reducer: transform request.
+			let req = buildRequest(actx, toolList, opts, signal);
+
+			// Inject ephemeral context into request messages (not persisted).
+			// Only on step 0 — on later steps, injecting a user message after
+			// tool results creates a role-order violation that makes the model
+			// think a new turn started, causing it to repeat itself.
+			if (ephemeralCtxMsg && step === 0) {
+				req = { ...req, messages: [...req.messages, ephemeralCtxMsg] };
+			}
+			for (const ext of extensions) {
+				const handler = ext.on?.["model-start"];
+				if (!handler) continue;
+				try {
+					const out = await handler(req, gctx);
+					if (
+						out !== undefined &&
+						out !== null &&
+						typeof out === "object" &&
+						"messages" in out
+					) {
+						req = out as ModelRequest;
+					}
+				} catch (err) {
+					await reportError(err, {
+						kind: "extension",
+						extensionName: ext.name,
+						event: "model-start",
+					});
+					throw err;
+				}
+			}
+
+			// 3b. Compute cache breakpoints for providers that support explicit caching.
+			// Placed after extensions modify messages so breakpoints target final positions.
+			const cacheBreakpoints = computeCacheBreakpoints(req.messages, step);
+			if (cacheBreakpoints.length > 0) {
+				req = { ...req, cacheBreakpoints };
+			}
+
+			// 3c. Stream from model.
+			const model = actx.model;
+			(gctx as { content: Content[] }).content = [];
+			const pendingToolCalls: ToolCallContent[] = [];
+			let iterFinishReason: FinishReason | null = null;
+			let iterUsage: Usage = { ...EMPTY_USAGE };
+			let committedAssistant: Message | null = null;
+
+			// emit('message-start')
+			emit({ type: "iteration-start", step, startedAt: Date.now() });
+			for (const ext of extensions) {
+				const handler = ext.on?.["message-start"];
+				if (handler) {
+					try {
+						await handler(gctx);
+					} catch (err) {
+						console.error(`[${ext.name}:message-start] ${formatError(err)}`);
+					}
+				}
+			}
+
+			try {
+				for await (const part of model.stream(req)) {
+					if (signal.aborted) break;
+					emit(part);
+
+					if (part.type === "text-delta") {
+						for (const ext of extensions) {
+							const h = ext.on?.["text-delta"];
+							if (h) {
+								try {
+									await h(part.delta, gctx);
+								} catch (err) {
+									console.error(`[${ext.name}:text-delta] ${formatError(err)}`);
+								}
+							}
+						}
+						const last = gctx.content[gctx.content.length - 1];
+						if (last && last.type === "text") {
+							(gctx.content as Content[])[gctx.content.length - 1] = {
+								...last,
+								text: last.text + part.delta,
+							};
+						} else {
+							gctx.content.push({ type: "text", text: part.delta });
+						}
+					} else if (part.type === "reasoning-delta") {
+						for (const ext of extensions) {
+							const h = ext.on?.["reasoning-delta"];
+							if (h) {
+								try {
+									await h(part.delta, gctx);
+								} catch (err) {
+									console.error(
+										`[${ext.name}:reasoning-delta] ${formatError(err)}`,
+									);
+								}
+							}
+						}
+						const last = gctx.content[gctx.content.length - 1];
+						if (last && last.type === "reasoning") {
+							(gctx.content as Content[])[gctx.content.length - 1] = {
+								...last,
+								text: last.text + part.delta,
+							};
+						} else {
+							gctx.content.push({ type: "reasoning", text: part.delta });
+						}
+					} else if (part.type === "tool-call-delta") {
+						for (const ext of extensions) {
+							const h = ext.on?.["tool-call-delta"];
+							if (h) {
+								try {
+									await h(
+										{
+											toolCallId: part.toolCallId,
+											toolName: part.toolName,
+											inputDelta: part.inputDelta,
+										},
+										gctx,
+									);
+								} catch (err) {
+									console.error(
+										`[${ext.name}:tool-call-delta] ${formatError(err)}`,
+									);
+								}
+							}
+						}
+					} else if (part.type === "tool-call") {
+						const tc: ToolCallContent = {
+							type: "tool-call",
+							toolCallId: part.toolCallId,
+							toolName: part.toolName,
+							input: part.input,
+						};
+						gctx.content.push(tc);
+						pendingToolCalls.push(tc);
+					} else if (part.type === "message-stop") {
+						committedAssistant = part.message;
+					} else if (part.type === "finish") {
+						iterFinishReason = part.reason;
+						iterUsage = part.usage;
+					} else if (part.type === "error") {
+						// Provider emitted a structured error (non-200 response, malformed body, etc.).
+						// Treat as a fatal stream error — surface it to the caller.
+						const providerErr =
+							part.error instanceof Error
+								? part.error
+								: new Error(String(part.error));
+						throw providerErr;
+					} else if (part.type === "abort") {
+						finishReason = "abort";
+						break;
+					}
+				}
+			} catch (err) {
+				await reportError(err, { kind: "provider", request: req });
+
+				// Commit partial/error assistant message to maintain sequence validity.
+				// The user message was already committed — if we throw without an
+				// assistant message, the next generate() call will fail with
+				// "user follows user" validation error.
+				const errorText =
+					err instanceof Error ? err.message : String(err);
+				const errorContent: Content[] =
+					gctx.content.length > 0
+						? [...gctx.content] // Preserve any partial text streamed before failure
+						: [{ type: "text", text: `[Error: ${errorText}]` }];
+				const errorMsg = toAssistantMessage(errorContent);
+				commitMessage(actx, errorMsg, emit, generateId);
+				finalAssistant = errorMsg;
+
+				throw err;
+			}
+
+			if (signal.aborted) break;
+
+			// 3c. Commit assistant message + emit('message-stop').
+			const asstMsg = committedAssistant ?? toAssistantMessage(gctx.content);
+			commitMessage(actx, asstMsg, emit, generateId);
+			finalAssistant = asstMsg;
+			lastIterUsage = iterUsage;
+			gctx.usage = addUsage(gctx.usage, iterUsage);
+
+			for (const ext of extensions) {
+				const handler = ext.on?.["message-stop"];
+				if (!handler) continue;
+				try {
+					await handler(asstMsg, gctx);
+				} catch (err) {
+					console.error(`[${ext.name}:message-stop] ${formatError(err)}`);
+				}
+			}
+
+			// Update actx.tokenCount to reflect current session size.
+			// Each API call sends the full conversation, so the last call's
+			// totalTokens IS the session size.
+			actx.tokenCount =
+				iterUsage.totalTokens ?? iterUsage.inputTokens + iterUsage.outputTokens;
+
+			// emit('model-stop')
+			for (const ext of extensions) {
+				const handler = ext.on?.["model-stop"];
+				if (handler) {
+					try {
+						await handler(gctx);
+					} catch (err) {
+						console.error(`[${ext.name}:model-stop] ${formatError(err)}`);
+					}
+				}
+			}
+
+			// 3d. Dispatch tool calls.
+			if (pendingToolCalls.length > 0) {
+				for (const tc of pendingToolCalls) {
+					if (signal.aborted) break;
+					const tool = tools.get(tc.toolName);
+					if (!tool) {
+						const msg: Message = {
+							role: "tool",
+							content: [
+								{
+									type: "tool-result",
+									toolCallId: tc.toolCallId,
+									toolName: tc.toolName,
+									output: {
+										type: "error-text",
+										value: `Unknown tool: ${tc.toolName}`,
+									},
+								},
+							],
+						};
+						commitMessage(actx, msg, emit, generateId);
+						toolResultMessages.push(msg);
+						continue;
+					}
+
+					// emit('tool-start') — intercept/modify/reject
+					const call: ToolCall = {
+						toolCallId: tc.toolCallId,
+						toolName: tc.toolName,
+						input: tc.input,
+					};
+					let effectiveCall = call;
+					let shortCircuited: ToolResult | null = null;
+
+					for (const ext of extensions) {
+						const handler = ext.on?.["tool-start"];
+						if (!handler) continue;
+						try {
+							const out = await handler(effectiveCall, gctx);
+							if (!out) continue;
+							if ("output" in out) {
+								shortCircuited = out as ToolResult;
+								break;
+							}
+							effectiveCall = out as ToolCall;
+						} catch (err) {
+							await reportError(err, {
+								kind: "extension",
+								extensionName: ext.name,
+								event: "tool-start",
+							});
+							throw err;
+						}
+					}
+
+					let result: ToolResult;
+					const toolStartedAt = Date.now();
+					emit({
+						type: "tool-execute-start",
+						call: effectiveCall,
+						startedAt: toolStartedAt,
+					});
+
+					if (shortCircuited) {
+						result = shortCircuited;
+					} else {
+						const timeoutMs = opts.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+						const toolPromise = dispatchTool({
+							call: effectiveCall,
+							tool,
+							extensions,
+							gctx,
+							reportError,
+							...(cacheConfig ? { cacheConfig } : {}),
+						});
+						const timeoutPromise = new Promise<never>((_, reject) =>
+							setTimeout(() => reject(new Error(`TOOL_TIMEOUT`)), timeoutMs),
+						);
+						// Race abort signal so tool execution is interrupted immediately on abort.
+						const abortPromise = new Promise<never>((_, reject) => {
+							if (signal.aborted) {
+								reject(signal.reason);
+								return;
+							}
+							signal.addEventListener("abort", () => reject(signal.reason), {
+								once: true,
+							});
+						});
+						try {
+							const outcome = await Promise.race([
+								toolPromise,
+								timeoutPromise,
+								abortPromise,
+							]);
+							result = outcome.result;
+						} catch (err) {
+							if (signal.aborted) {
+								// Abort won the race — break out of tool loop.
+								break;
+							}
+							// Synthesize an error result for ANY failure (timeout,
+							// network, unexpected throw). This ensures every tool-call
+							// always gets a matching tool-result — no orphaned state.
+							const errorValue =
+								err instanceof Error && err.message === "TOOL_TIMEOUT"
+									? `Tool "${effectiveCall.toolName}" timed out after ${timeoutMs}ms. Retry with a longer timeout or simplify the request.`
+									: err instanceof Error
+										? `Tool execution failed: ${err.message}`
+										: "Tool call failed (internal error during execution).";
+							result = {
+								toolCallId: effectiveCall.toolCallId,
+								toolName: effectiveCall.toolName,
+								output: {
+									type: "error-text",
+									value: errorValue,
+								},
+							};
+							await reportError(err, {
+								kind: "tool",
+								call: effectiveCall,
+							});
+						}
+					}
+
+					// emit('tool-stop') — reducer
+					for (const ext of extensions) {
+						const handler = ext.on?.["tool-stop"];
+						if (!handler) continue;
+						try {
+							const out = await handler(result, gctx);
+							if (out !== undefined) result = out;
+						} catch (err) {
+							await reportError(err, {
+								kind: "extension",
+								extensionName: ext.name,
+								event: "tool-stop",
+							});
+						}
+					}
+
+					emit({
+						type: "tool-execute-finish",
+						call: effectiveCall,
+						result,
+						startedAt: toolStartedAt,
+						endedAt: Date.now(),
+					});
+
+					const msg: Message = {
+						role: "tool",
+						content: [
+							{
+								type: "tool-result",
+								toolCallId: result.toolCallId,
+								toolName: result.toolName,
+								output: result.output,
+							},
+						],
+					};
+					commitMessage(actx, msg, emit, generateId);
+					toolResultMessages.push(msg);
+				}
+
+				// 3d-cleanup. If abort interrupted the tool loop, synthesize error
+				// results for any tool calls that never got a response. This keeps
+				// the message history valid (every tool-call has a tool-result).
+				if (signal.aborted) {
+					const fulfilled = new Set(
+						toolResultMessages.map((m) => {
+							const c = m.content[0];
+							return c && c.type === "tool-result" ? c.toolCallId : "";
+						}),
+					);
+					for (const tc of pendingToolCalls) {
+						if (fulfilled.has(tc.toolCallId)) continue;
+						const abortMsg: Message = {
+							role: "tool",
+							content: [
+								{
+									type: "tool-result",
+									toolCallId: tc.toolCallId,
+									toolName: tc.toolName,
+									output: {
+										type: "error-text",
+										value: "Tool call aborted.",
+									},
+								},
+							],
+						};
+						commitMessage(actx, abortMsg, emit, generateId);
+						toolResultMessages.push(abortMsg);
+					}
+				}
+			}
+
+			// 3e. Step finished.
+			const iterReason = iterFinishReason ?? "stop";
+			emit({
+				type: "iteration-finish",
+				step,
+				endedAt: Date.now(),
+				finishReason: iterReason,
+				usage: iterUsage,
+			});
+			finishReason = iterReason;
+
+			const shouldContinue =
+				iterReason === "tool-calls" &&
+				pendingToolCalls.length > 0 &&
+				step + 1 < gctx.maxSteps;
+			if (!shouldContinue) break;
+			step++;
+			(gctx as { stepCount: number }).stepCount = step;
+		}
+
+		// 4. emit('generate-stop').
+		generateStopFired = true;
+		for (const ext of extensions) {
+			const handler = ext.on?.["generate-stop"];
+			if (!handler) continue;
+			try {
+				await handler(gctx);
+			} catch (err) {
+				console.error(`[${ext.name}:generate-stop] ${formatError(err)}`);
+			}
+		}
+
+		// 5. Result.
+		const result: GenerateResult = {
+			generateId,
+			message: finalAssistant ?? { role: "assistant", content: [] },
+			toolResultMessages,
+			usage: gctx.usage,
+			finishReason,
+			steps: step + 1,
+		};
+		// actx.tokenCount already updated in the model-stop block above.
+		emit({ type: "generate-finish", result });
+		stream.close();
+		signals.dispose();
+		return result;
+	} catch (err) {
+		// Fire generate-stop even on error so extensions (e.g. session persistence)
+		// can flush any committed messages before the error propagates.
+		if (!generateStopFired) {
+			for (const ext of extensions) {
+				const handler = ext.on?.["generate-stop"];
+				if (!handler) continue;
+				try {
+					await handler(gctx);
+				} catch (stopErr) {
+					console.error(`[${ext.name}:generate-stop] ${formatError(stopErr)}`);
+				}
+			}
+		}
+
+		// Safety net: if we committed user message(s) this turn but no assistant
+		// message followed (e.g. provider timeout/error before any response),
+		// commit a synthetic assistant to maintain sequence validity.
+		// Without this, the next generate() call would fail with
+		// "user follows user" validation error.
+		if (!finalAssistant) {
+			const lastMsg = actx.messages[actx.messages.length - 1];
+			if (lastMsg && lastMsg.role !== "assistant" && lastMsg.role !== "system") {
+				const errorText = signal.aborted
+					? "The operation was aborted."
+					: err instanceof Error
+						? err.message
+						: String(err);
+				const fallbackMsg: Message = {
+					role: "assistant",
+					content: [{ type: "text", text: `[Error: ${errorText}]` }],
+					...(generateId ? { generateId } : {}),
+				};
+				try {
+					actx.appendMessage(fallbackMsg);
+				} catch {
+					// If even the fallback commit fails (shouldn't happen), don't mask the original error
+				}
+			}
+		}
+
+		await reportError(err, { kind: "loop" });
+		signals.dispose();
+		throw err;
+	}
+}