agentLoop.ts

/**
 * In-process tool-call agent loop for `Models.generate({ toolMode: 'auto' })`.
 *
 * Each iteration: (1) call `models.generate` with the running message list,
 * (2) if the model emitted tool calls, dispatch each via `opts.toolHandlers`,
 * (3) append the tool results to the message list, repeat. Terminate when the
 * model returns a non-`tool_calls` finish reason or when the iteration cap trips.
 *
 * Analytics: the loop calls back through `models.generate(..., {toolMode: 'return'})`
 * per iteration so each backend round flows the single-shot path in `Models.ts` and
 * writes its own `hdb_model_calls` row. The outer auto call stays out of the table.
 *
 * **Abort wiring** (commit 3). Each invocation creates a loop-level
 * `AbortController` composed with the caller's signal via `AbortSignal.any`. The
 * composed signal flows to both the inner `models.generate` call and the
 * `ToolHandlerContext.signal` handlers receive. Today the loop-level controller is
 * only fired externally (caller aborts → composed signal aborts); commit 4 wires
 * it to also fire on budget trips so an in-flight LLM call cancels cleanly.
 *
 * Streaming auto path + `opts.conversation.append` hook on both sync and streaming.
 * The streaming loop yields each round's content / tool-call deltas to the caller as
 * they arrive, accumulates the round's tool-call assembly internally, and treats
 * `finishReason` as an INTERNAL signal: it is stripped from every forwarded chunk and
 * re-emitted as exactly one terminal chunk AFTER the terminal assistant turn has been
 * persisted, so a consumer that stops on the finish-reason chunk can never race past
 * the conversation append. Tools run between rounds; the next backend stream resumes.
 * Budget / abort / error-mode semantics match the sync path, with one streaming-specific
 * gap: `maxToolTokens` / `maxCostUsd` are not yet enforced for streamed calls because
 * `GenerateChunk` doesn't expose `usage` in v1 (follow-up to extend the chunk shape +
 * backend final-chunk handling).
 *
 * Resilience posture (this module is foundational infra — fail loud, never silent):
 *   - Handler lookup uses `Object.hasOwn` + a callable check; a model-emitted tool name
 *     that collides with an Object prototype member (`toString`, `constructor`, …) does
 *     NOT resolve a built-in as a handler.
 *   - Missing handler splits two ways: a name the caller DECLARED in `tools` but didn't
 *     supply a handler for is a caller config bug (hard `ClientError(400)`); an UNdeclared
 *     name is a model hallucination, surfaced as a recoverable tool error (`toolErrorMode`
 *     decides recover-vs-abort).
 *   - A token/cost budget set against a backend that reports no `usage` warns once that it
 *     is unenforceable rather than silently no-opping.
 *   - An incomplete streamed tool call (id without a name) is recorded in the trace + warned,
 *     not silently dropped.
 *   - `toolErrorMode: 'abort'` throws BEFORE the conversation sink sees the round's tool
 *     turns, so the store never holds a recover-style error turn the model never consumed.
 *
 * Modes still deferred to follow-ups throw 501 at entry:
 *   - `toolArgValidation: 'strict' | 'lenient'`  → JSON Schema validator (TBD)
 *   - `maxToolTokens` / `maxCostUsd` (streaming) → backend `usage` on chunks (TBD)
 *
 * Registry seam: v1 dispatches via caller-supplied `opts.toolHandlers`. #615 replaces
 * that lookup with a `scope.resources` resolution using the same call signature — the
 * declared-vs-undeclared split maps onto resolvable-but-misconfigured vs unknown.
 */
import { ClientError, ServerError } from '../../utility/errors/hdbError.ts';
import { logger } from '../../utility/logging/logger.ts';
import type {
	AccountingContext,
	GenerateChunk,
	GenerateInput,
	GenerateOpts,
	GenerateResult,
	Message,
	Models,
	TokenUsage,
	ToolCall,
	ToolDef,
	ToolHandler,
	ToolHandlerContext,
	ToolTraceEntry,
} from './types.ts';

const DEFAULT_MAX_ITERATIONS = 10;
const DEFAULT_MAX_RESULT_BYTES = 65_536;

export interface RunAgentLoopArgs {
	models: Models;
	input: GenerateInput;
	opts: GenerateOpts;
	accounting: AccountingContext;
	signal?: AbortSignal;
}

export async function runAgentLoop(args: RunAgentLoopArgs): Promise<GenerateResult> {
	const { models, opts, accounting, signal: callerSignal } = args;

	// v1 gates: surface declared on GenerateOpts, runtime fills in incrementally.
	// Throw a clear 501 at entry rather than silently downgrading to default behavior —
	// the alternative (ignore unsupported mode) would mask caller mistakes.
	guardUnsupportedModes(opts);

	const maxIterations = opts.maxToolIterations ?? DEFAULT_MAX_ITERATIONS;
	const maxResultBytes = opts.toolResultMaxBytes ?? DEFAULT_MAX_RESULT_BYTES;
	const handlers = opts.toolHandlers ?? {};
	const parallelism = opts.toolParallelism ?? 'parallel';
	const errorMode = opts.toolErrorMode ?? 'recover';
	const maxToolTokens = opts.maxToolTokens;
	const maxCostUsd = opts.maxCostUsd;
	const conversation = opts.conversation;

	const { messages, tools, system } = normalizeInput(args.input);
	// Names the CALLER declared as tools (object-form input). Used to split the
	// missing-handler case: a declared tool with no handler is a caller config bug
	// (hard fail); an UNdeclared name is a model hallucination (recover). See
	// `runSingleToolCall`.
	const declaredToolNames = collectDeclaredToolNames(tools);
	const trace: ToolTraceEntry[] = [];
	// Cumulative usage tallies across all iterations of this loop invocation. Used to
	// trip `maxToolTokens` / `maxCostUsd` after each backend round.
	let totalTokens = 0;
	let totalCostUsd = 0;
	// Warn-once latch: a token/cost budget is set but the backend isn't reporting
	// usage, so the cap can't be measured. We refuse to silently pretend it's enforced.
	let budgetUnmeasurableWarned = false;

	// `conversation` is a one-way SINK for NEW turns produced by this loop — the loop
	// does NOT re-append the caller's input messages, even when they include user
	// turns. Echoing input back into the caller's store would corrupt it (the caller
	// already added their own prompt) and scramble ordering for multi-turn history.
	// The caller owns turn 0; the loop owns whatever assistant/tool turns it produces.

	// Loop-level abort controller — fired internally on budget trips (commit 4 wires
	// that) and on every loop exit (success, throw, abort) via the `finally` below.
	// Composed with the caller's signal so an external `caller.abort()` ALSO fires
	// the loop's signal (handlers and the in-flight backend call both react). The
	// composed signal is the only signal that flows to inner calls.
	const loopController = new AbortController();
	const composedSignal = composeAbortSignal(callerSignal, loopController.signal);

	// Strip loop-only knobs from what flows back into `models.generate`. The `toolMode:
	// 'return'` override is what prevents the outer entry point from re-entering this loop.
	// `signal` is swapped to the composed signal so `Models.generate` (and through it,
	// the backend) see budget-trip and caller-abort cancellations the same way.
	const innerOpts: GenerateOpts = { ...opts, toolMode: 'return', signal: composedSignal };

	try {
		for (let iteration = 1; iteration <= maxIterations; iteration++) {
			// Pre-iteration abort check — if the caller (or a future budget trip) fired
			// the composed signal between rounds, bail before paying for another backend
			// call. The inner `models.generate` would itself throw on the in-flight check,
			// but throwing here saves the round-trip and the spurious analytics row.
			composedSignal.throwIfAborted();

			const result = await models.generate(buildInnerInput(messages, tools, system), innerOpts);

			// Re-check abort the instant the backend round returns, BEFORE any budget
			// accounting, assistant append, or tool dispatch. A well-behaved backend
			// throws on an in-flight abort; an ill-behaved one (community backend that
			// ignores its signal) can resolve normally after the caller aborted. Without
			// this check the loop would run side-effecting handlers for a cancelled
			// request and then misreport the outcome as a budget/tool error instead of
			// an abort.
			composedSignal.throwIfAborted();

			logger.debug?.(
				`[models] auto-loop iteration ${iteration}: finishReason=${result.finishReason} toolCalls=${result.toolCalls?.length ?? 0} cumulativeTokens=${totalTokens}`
			);

			// A token/cost budget is only as good as the backend's usage reporting. If a
			// cap is set but this round reported no usage, the cap is unmeasurable — warn
			// once rather than letting the caller believe spend is bounded when it isn't.
			if (
				(maxToolTokens !== undefined || maxCostUsd !== undefined) &&
				result.usage === undefined &&
				!budgetUnmeasurableWarned
			) {
				budgetUnmeasurableWarned = true;
				logger.warn?.(
					`[models] auto-loop token/cost budget set but backend '${opts.model ?? 'default'}' reported no usage; budget is unenforceable for this run (maxToolIterations still applies)`
				);
			}

			// Tally this round's usage BEFORE deciding terminal vs continue. A round
			// that crosses the cap trips even if it would otherwise have been the last
			// one — the cap is on what we paid for, not on what we'd have paid for next.
			// Cost trip semantics: `>= cap`, so `maxCostUsd: 0` blocks every call rather
			// than dormantly admitting all of them until a real rate card lands and then
			// abruptly blocking everything. Token trip uses `>=` for symmetry.
			//
			// Discarded-content asymmetry: a TERMINAL round that trips returns
			// BudgetExceededError instead of the final assistant content. The content is
			// in `messages` (the loop's running state) but neither `partialTrace` nor the
			// thrown error surfaces it. Callers that need terminal content even on
			// budget-trip should set `maxToolTokens` / `maxCostUsd` conservatively or read
			// the per-iteration analytics rows (one row per round in `hdb_model_calls`).
			totalTokens += sumTokens(result.usage);
			totalCostUsd += computeCallCostUsd(result.usage, opts.model);
			if (maxToolTokens !== undefined && totalTokens >= maxToolTokens) {
				throw new BudgetExceededError(
					'tokens',
					`agent loop exceeded maxToolTokens=${maxToolTokens} (cumulative=${totalTokens})`,
					trace
				);
			}
			if (maxCostUsd !== undefined && totalCostUsd >= maxCostUsd) {
				throw new BudgetExceededError(
					'cost',
					`agent loop exceeded maxCostUsd=${maxCostUsd} (cumulative=${totalCostUsd})`,
					trace
				);
			}

			const calls = result.toolCalls;
			// Backends (notably OpenAI) leave `content` as `null` / undefined on tool-call
			// rounds. `Message.content` and `ConversationTurn.content` are typed as a
			// required string — coerce to '' at the seam.
			const assistantContent = result.content ?? '';
			if (result.finishReason !== 'tool_calls' || !calls || calls.length === 0) {
				// Terminal: model produced a final answer (stop / length / content_filter), or it
				// signaled tool_calls but emitted none. Append final assistant turn to the
				// conversation hook (if set), then pass the result through; attach the trace
				// when the caller asked for it.
				if (conversation && assistantContent) {
					await conversation.append({ role: 'assistant', content: assistantContent });
				}
				// A `tool_calls` finishReason with no dispatchable calls (e.g. the backend
				// dropped malformed tool-call args) is terminal — coerce it to 'stop' so an
				// auto-mode caller never sees a `tool_calls` finishReason (auto resolves calls
				// internally) pointing at calls that aren't there, and never a `null` content.
				// Mirrors the streaming path's terminalReason fold.
				const terminal: GenerateResult =
					result.finishReason === 'tool_calls'
						? { ...result, finishReason: 'stop', content: assistantContent }
						: result;
				return opts.includeToolTrace ? { ...terminal, trace } : terminal;
			}

			messages.push({ role: 'assistant', content: assistantContent, toolCalls: calls });
			if (conversation) {
				await conversation.append({
					role: 'assistant',
					content: assistantContent,
					toolCalls: calls,
				});
			}

			const ctx: ToolHandlerContext = { signal: composedSignal, accounting };
			const dispatched = await dispatchToolCalls(
				calls,
				handlers,
				declaredToolNames,
				ctx,
				iteration,
				maxResultBytes,
				parallelism
			);

			// Post-dispatch abort check — covers the LAST-iteration case: if the signal
			// fired during this round's handlers, we'd otherwise skip the top-of-loop check
			// and throw `BudgetExceededError` (misleading: the budget never tripped). Fire
			// the abort here so the caller gets the correct error class. Earlier iterations
			// pick this up on the next round's top-of-loop check.
			composedSignal.throwIfAborted();

			// Trace + the in-memory message list always record every tool result in CALL
			// order (the trace mirrors what the model emitted, not which handler finished
			// first). The EXTERNAL conversation sink is handled separately below so the
			// abort-mode throw can run BEFORE we persist turns the model never consumes.
			for (const dispatchResult of dispatched) {
				trace.push(dispatchResult.entry);
				messages.push({
					role: 'tool',
					content: dispatchResult.toolMessageContent,
					toolCallId: dispatchResult.entry.toolCallId,
				});
			}

			// `toolErrorMode: 'abort'`: any handler failure terminates the loop. Throw
			// BEFORE the conversation sink sees this round's tool turns — abort mode
			// returns the error to the caller instead of recovering, so persisting a
			// recover-style tool-error turn the model never reads would leave the store
			// inconsistent with what actually happened. The trace (built above) still
			// carries the failing entry via `ToolHandlerError.partialTrace`.
			if (errorMode === 'abort') {
				const failed = dispatched.find((d) => d.originalError !== undefined);
				if (failed) {
					throw new ToolHandlerError(failed.entry.toolName, failed.entry.toolCallId, trace, failed.originalError);
				}
			}

			// Continue path: persist this round's tool turns to the conversation sink.
			if (conversation) {
				for (const dispatchResult of dispatched) {
					await conversation.append({
						role: 'tool',
						toolCallId: dispatchResult.entry.toolCallId,
						content: dispatchResult.toolMessageContent,
					});
				}
			}
		}

		// Hit `maxToolIterations` without a terminal finishReason — the model kept calling tools.
		// Always include the trace on the error path (independent of `includeToolTrace`) so
		// callers can debug an exhausted budget without re-running with tracing on.
		throw new BudgetExceededError('iterations', `agent loop exceeded maxToolIterations=${maxIterations}`, trace);
	} finally {
		// Always abort the loop controller on exit (success, throw, or external abort).
		// Cleans up `AbortSignal.any`'s listener on `callerSignal` so a session-scoped caller
		// signal doesn't accumulate listeners across many `runAgentLoop` invocations, and
		// signals any sibling handlers still running in the background after a Promise.all
		// rejection (missing-handler or aborted-mid-flight) to bail out promptly.
		loopController.abort();
	}
}

interface DispatchedToolCall {
	entry: ToolTraceEntry;
	toolMessageContent: string;
	/**
	 * The original thrown value when the handler / serialization failed and recover
	 * mode caught it. Preserved alongside the formatted `entry.error` so abort mode
	 * can surface the cause unmodified via `ToolHandlerError.cause`. Undefined when
	 * the handler succeeded.
	 */
	originalError?: unknown;
}

async function dispatchToolCalls(
	calls: ToolCall[],
	handlers: Record<string, ToolHandler>,
	declaredToolNames: Set<string>,
	ctx: ToolHandlerContext,
	iteration: number,
	maxResultBytes: number,
	parallelism: 'parallel' | 'serial'
): Promise<DispatchedToolCall[]> {
	// Single-call rounds use the serial path even when 'parallel' is selected — the
	// settled-wrapping path adds nothing on one element and the serial path's stack
	// trace is more readable in errors.
	if (parallelism === 'serial' || calls.length <= 1) {
		const out: DispatchedToolCall[] = [];
		for (const call of calls) {
			out.push(await runSingleToolCall(call, handlers, declaredToolNames, ctx, iteration, maxResultBytes));
		}
		return out;
	}
	// Parallel: handlers race concurrently. `runSingleToolCall` only throws on missing
	// handler or cooperative abort — handler errors are caught inline and surface via
	// `originalError`. `Promise.all` rejects on first throw, which is what we want for
	// those two cases: surface the throw immediately so the loop's `finally` can fire
	// `loopController.abort` and cancel siblings still in flight, instead of waiting
	// for every sibling to complete (which `Promise.allSettled` would force).
	//
	// Concurrent-rejection caveat: when MULTIPLE siblings reject at the same time
	// (e.g. several missing handlers, or several handlers reacting to a cooperative
	// abort), `Promise.all` only awaits the first rejection — the rest become
	// unhandled-rejection warnings (and crash under `--unhandled-rejections=throw`).
	// Attach a no-op catch to each promise so the runtime sees every rejection as
	// handled while still letting `Promise.all` settle on the first one.
	const promises = calls.map((call) =>
		runSingleToolCall(call, handlers, declaredToolNames, ctx, iteration, maxResultBytes)
	);
	for (const p of promises) p.catch(() => {});
	return Promise.all(promises);
}

async function runSingleToolCall(
	call: ToolCall,
	handlers: Record<string, ToolHandler>,
	declaredToolNames: Set<string>,
	ctx: ToolHandlerContext,
	iteration: number,
	maxResultBytes: number
): Promise<DispatchedToolCall> {
	// Guard: don't start a side-effecting handler if the caller has already
	// aborted. The catch below already rethrows AbortError, so a pre-aborted
	// signal that fires after entry but before the handler await is also covered.
	ctx.signal?.throwIfAborted();

	const entry: ToolTraceEntry = {
		iteration,
		toolCallId: call.id,
		toolName: call.name,
		// Shallow-copy so the trace's view of "what the model emitted" doesn't shift if a
		// handler mutates its `args` parameter (legitimate pattern). Deep mutations to
		// nested objects can still leak — common-case flat-object args are covered.
		arguments: { ...call.arguments },
		durationMs: 0,
	};

	// Handler resolution. Use `Object.hasOwn` + a callable check rather than a plain
	// `handlers[call.name]` lookup: a model can emit a tool name that collides with an
	// inherited Object prototype member (`toString`, `constructor`, `__proto__`, ...),
	// and a bare index would resolve that built-in as a "handler" and invoke it. Model
	// output is untrusted input at this boundary — only an own, callable property counts.
	const handler =
		Object.hasOwn(handlers, call.name) && typeof handlers[call.name] === 'function' ? handlers[call.name] : undefined;
	if (!handler) {
		if (declaredToolNames.has(call.name)) {
			// The caller DECLARED this tool but supplied no (callable) handler for it.
			// That's a caller config bug, not something the model can recover from —
			// hard fail. (#615 swaps this lookup for a `scope.resources` registry
			// resolution; same split — resolvable-but-misconfigured stays a hard fail.)
			throw new ClientError(`No handler registered for declared tool '${call.name}' (call id ${call.id})`, 400);
		}
		// Undeclared tool name: the model hallucinated a tool that doesn't exist. This is
		// the EXPECTED failure mode for an LLM, not a caller fault — surface it as a
		// recoverable tool error so `toolErrorMode: 'recover'` feeds it back and the model
		// can self-correct, while `'abort'` (via `originalError`) still stops the loop.
		logger.warn?.(
			`[models] auto-loop: model called unknown tool '${call.name}' (call id ${call.id}); no such tool declared`
		);
		const unknownToolError = new ClientError(`Unknown tool '${call.name}': no such tool is available`, 400);
		entry.error = errorInfo(unknownToolError);
		return {
			entry,
			toolMessageContent: JSON.stringify({ error: entry.error.message }),
			originalError: unknownToolError,
		};
	}

	const handlerStart = performance.now();
	let toolMessageContent: string;
	let originalError: unknown;
	// Wrap BOTH the handler call AND result serialization in the recover catch.
	// `JSON.stringify` throws on BigInt and circular refs — both trivially produced by
	// handlers that return raw DB rows or Resource instances. Without this, a
	// serialization failure crashes the entire loop instead of becoming a tool error
	// the model can react to (the `toolErrorMode: 'recover'` contract).
	try {
		const handlerOutput = await handler(call.arguments, ctx);
		const serialized = serializeToolResult(handlerOutput, maxResultBytes);
		entry.result = serialized.content;
		if (serialized.truncated) {
			entry.truncated = true;
			entry.totalBytes = serialized.totalBytes;
		}
		toolMessageContent = serialized.content;
	} catch (err) {
		// Cooperative cancellation is NOT a tool error — rethrow so the loop's
		// abort path (top-of-loop / post-dispatch `throwIfAborted`) classifies it
		// correctly. Without this, AbortError would land in `entry.error` and the
		// caller would see `BudgetExceededError` on the last iteration, or a
		// bogus `{error: 'aborted'}` tool message threaded into the conversation.
		// The trace entry is abandoned (the loop builds an aborted-path trace later).
		if (ctx.signal?.aborted) throw err;
		// Handler error. Populate entry.error so the trace records the failure, build
		// the recover-mode tool-message envelope, and stash the original throw so
		// `toolErrorMode: 'abort'` (checked in the main loop after dispatch) can
		// surface the cause unmodified.
		originalError = err;
		entry.error = errorInfo(err);
		toolMessageContent = JSON.stringify({ error: entry.error.message });
	}
	entry.durationMs = performance.now() - handlerStart;

	return { entry, toolMessageContent, originalError };
}

/**
 * Mirror of `backendHelpers.composeSignal` but composing a caller signal with an
 * INTERNAL controller's signal (not a timeout). Returns the internal signal alone
 * when no caller signal exists, the caller signal alone when no internal controller
 * is needed (today never — we always create one), and a composed signal otherwise.
 *
 * `AbortSignal.any` requires Node 20+, which matches Harper's engines floor.
 */
function composeAbortSignal(caller: AbortSignal | undefined, internal: AbortSignal): AbortSignal {
	if (!caller) return internal;
	return AbortSignal.any([caller, internal]);
}

export async function* runAgentLoopStream(args: RunAgentLoopArgs): AsyncIterable<GenerateChunk> {
	const { models, opts, accounting, signal: callerSignal } = args;

	guardUnsupportedModes(opts);

	const maxIterations = opts.maxToolIterations ?? DEFAULT_MAX_ITERATIONS;
	const maxResultBytes = opts.toolResultMaxBytes ?? DEFAULT_MAX_RESULT_BYTES;
	const handlers = opts.toolHandlers ?? {};
	const parallelism = opts.toolParallelism ?? 'parallel';
	const errorMode = opts.toolErrorMode ?? 'recover';
	const conversation = opts.conversation;
	// Streaming + token/cost budgets: backends don't emit `usage` on `GenerateChunk`
	// in v1 (the type has no `usage` field on chunks), so cumulative usage isn't
	// observable from the stream. The iteration budget still applies. Wiring
	// streaming budgets requires extending `GenerateChunk` and updating each
	// backend's stream-final-chunk handling — a follow-up to this PR.
	if (opts.maxToolTokens !== undefined || opts.maxCostUsd !== undefined) {
		throw new ServerError(
			`maxToolTokens / maxCostUsd are not yet supported for generateStream (streamed usage not exposed in v1)`,
			501
		);
	}

	const { messages, tools, system } = normalizeInput(args.input);
	const declaredToolNames = collectDeclaredToolNames(tools);
	const trace: ToolTraceEntry[] = [];

	const loopController = new AbortController();
	const composedSignal = composeAbortSignal(callerSignal, loopController.signal);
	const innerOpts: GenerateOpts = { ...opts, toolMode: 'return', signal: composedSignal };

	// `conversation` is a one-way SINK for NEW turns produced by this loop — see
	// `runAgentLoop` for the rationale. Streaming path applies the same contract.

	try {
		for (let iteration = 1; iteration <= maxIterations; iteration++) {
			composedSignal.throwIfAborted();

			// Stream this round: yield content + tool-call deltas to the caller as they
			// arrive, while internally assembling the round's content and tool-call shape.
			let accumulatedContent = '';
			const toolCallAssembly = new Map<string, Partial<ToolCall>>();
			let finishReason: GenerateResult['finishReason'] | undefined;

			const stream = models.generateStream(buildInnerInput(messages, tools, system), innerOpts);
			for await (const chunk of stream) {
				// Defense-in-depth: well-behaved backends honor `opts.signal` via the
				// fetch they hand it to. An ill-behaved community backend that doesn't
				// observe its signal would otherwise keep streaming after a caller abort.
				composedSignal.throwIfAborted();

				if (chunk.deltaContent !== undefined) {
					accumulatedContent += chunk.deltaContent;
				}
				if (chunk.deltaToolCalls) {
					for (const delta of chunk.deltaToolCalls) {
						mergeToolCallDelta(toolCallAssembly, delta);
					}
				}
				if (chunk.finishReason) {
					finishReason = chunk.finishReason;
				}
				// `finishReason` is an INTERNAL signal — never forward it inline. We re-emit
				// exactly one terminal chunk after the loop, AFTER the terminal turn has been
				// appended to the conversation sink (see below). Forwarding it here would let a
				// consumer that stops on the first finish-reason chunk close this generator at
				// the `yield` before the append runs, delivering a response that never persists.
				// The deltas (content / tool-call shape) still flow through untouched.
				if (chunk.deltaContent !== undefined || chunk.deltaToolCalls) {
					const cleaned: GenerateChunk = {};
					if (chunk.deltaContent !== undefined) cleaned.deltaContent = chunk.deltaContent;
					if (chunk.deltaToolCalls) cleaned.deltaToolCalls = chunk.deltaToolCalls;
					yield cleaned;
				}
			}

			const finalToolCalls = completeToolCallAssembly(toolCallAssembly);
			// Surface any assembled-but-incomplete tool calls (id arrived, name never did)
			// instead of silently dropping them. `completeToolCallAssembly` keeps only
			// dispatchable (id + name) calls; a missing-name partial usually means a
			// truncated stream. Record it in the trace + warn so the drop is observable.
			if (finalToolCalls.length < toolCallAssembly.size) {
				for (const [id, partial] of toolCallAssembly) {
					if (!partial.name) {
						logger.warn?.(
							`[models] auto-loop: dropping incomplete streamed tool call id=${id} (no tool name assembled; stream likely truncated)`
						);
						trace.push({
							iteration,
							toolCallId: id,
							toolName: '<incomplete>',
							arguments: partial.arguments ?? {},
							durationMs: 0,
							error: { name: 'IncompleteToolCall', message: 'streamed tool call missing name; dropped' },
						});
					}
				}
			}

			logger.debug?.(
				`[models] auto-loop stream iteration ${iteration}: finishReason=${finishReason ?? 'none'} toolCalls=${finalToolCalls.length}`
			);

			// Continue-vs-terminal:
			// - Hand off to tool dispatch when calls assembled AND the backend signalled
			//   tool_calls OR didn't signal anything at all. The "no finishReason" case
			//   covers proxy-truncated streams: every in-tree backend (openai, anthropic,
			//   bedrock) emits a tail-flush `deltaToolCalls` without a finishReason when
			//   the upstream connection drops mid-stream. Treating that as terminal would
			//   silently drop the assembled tool calls — the backend's recovery would be
			//   undone by this loop.
			// - Otherwise, terminal: yield a synthetic 'stop' chunk if the consumer didn't
			//   receive a terminal finishReason inline (degenerate streams, or the
			//   suppressed `tool_calls` finishReason with zero assembled calls).
			const hasToolCalls = finalToolCalls.length > 0;
			const continueWithToolCalls = hasToolCalls && (finishReason === 'tool_calls' || finishReason === undefined);

			if (!continueWithToolCalls) {
				// Terminal. Persist the final assistant turn to the conversation sink FIRST,
				// then emit exactly one terminal chunk. Because the loop suppressed every
				// inline finishReason, this `yield` is the only finish-reason the consumer
				// sees — and it lands after the append, so a consumer that stops on it cannot
				// race past the persistence.
				if (conversation && accumulatedContent) {
					await conversation.append({ role: 'assistant', content: accumulatedContent });
				}
				// `tool_calls` with zero dispatchable calls can't honestly be reported as the
				// terminal reason (there are no calls); fold it and the no-signal case to 'stop'.
				const terminalReason = finishReason && finishReason !== 'tool_calls' ? finishReason : 'stop';
				yield { finishReason: terminalReason };
				return;
			}

			// Continue the loop: dispatch tools, append messages, resume on next iteration.
			const assistantMessage: Message = {
				role: 'assistant',
				content: accumulatedContent,
				toolCalls: finalToolCalls,
			};
			messages.push(assistantMessage);
			if (conversation) {
				await conversation.append({
					role: 'assistant',
					content: accumulatedContent,
					toolCalls: finalToolCalls,
				});
			}

			const ctx: ToolHandlerContext = { signal: composedSignal, accounting };
			const dispatched = await dispatchToolCalls(
				finalToolCalls,
				handlers,
				declaredToolNames,
				ctx,
				iteration,
				maxResultBytes,
				parallelism
			);

			composedSignal.throwIfAborted();

			// Trace + in-memory messages always record every result; the external
			// conversation sink is deferred past the abort-mode throw (same rationale as
			// the sync path — don't persist tool turns the model never consumes on abort).
			for (const d of dispatched) {
				trace.push(d.entry);
				messages.push({
					role: 'tool',
					content: d.toolMessageContent,
					toolCallId: d.entry.toolCallId,
				});
			}

			if (errorMode === 'abort') {
				const failed = dispatched.find((d) => d.originalError !== undefined);
				if (failed) {
					throw new ToolHandlerError(failed.entry.toolName, failed.entry.toolCallId, trace, failed.originalError);
				}
			}

			if (conversation) {
				for (const d of dispatched) {
					await conversation.append({
						role: 'tool',
						toolCallId: d.entry.toolCallId,
						content: d.toolMessageContent,
					});
				}
			}
		}

		throw new BudgetExceededError('iterations', `agent loop exceeded maxToolIterations=${maxIterations}`, trace);
	} finally {
		loopController.abort();
	}
}

/**
 * Update the in-flight assembly map with one streamed tool-call delta. Streaming
 * backends may send the same `id` multiple times with partial `name` / `arguments`;
 * we merge them in arrival order. Some backends pre-assemble and send the full
 * call as a single delta — same code path, single update.
 *
 * Backends that stream `arguments` as accumulating JSON string fragments must
 * parse before yielding (delta.arguments is typed as `object`); shape assembly
 * lives in this loop, fragment assembly lives in the backend.
 */
function mergeToolCallDelta(map: Map<string, Partial<ToolCall>>, delta: Partial<ToolCall>): void {
	if (!delta.id) return;
	const existing: Partial<ToolCall> = map.get(delta.id) ?? { id: delta.id };
	if (delta.name) existing.name = delta.name;
	if (delta.arguments) {
		existing.arguments = { ...existing.arguments, ...delta.arguments };
	}
	map.set(delta.id, existing);
}

function completeToolCallAssembly(map: Map<string, Partial<ToolCall>>): ToolCall[] {
	const out: ToolCall[] = [];
	for (const partial of map.values()) {
		if (partial.id && partial.name) {
			out.push({
				id: partial.id,
				name: partial.name,
				arguments: partial.arguments ?? {},
			});
		}
	}
	return out;
}

function guardUnsupportedModes(opts: GenerateOpts): void {
	const validationMode = opts.toolArgValidation ?? 'none';
	if (validationMode !== 'none') {
		throw new ServerError(
			`toolArgValidation: '${validationMode}' is not yet implemented; v1 supports 'none' only`,
			501
		);
	}
}

function buildInnerInput(
	messages: Message[],
	tools: ToolDef[] | undefined,
	system: string | undefined
): { messages: Message[]; tools?: ToolDef[]; system?: string } {
	const inner: { messages: Message[]; tools?: ToolDef[]; system?: string } = { messages };
	if (tools) inner.tools = tools;
	if (system) inner.system = system;
	return inner;
}

function normalizeInput(input: GenerateInput): {
	messages: Message[];
	tools?: ToolDef[];
	system?: string;
} {
	if (typeof input === 'string') {
		return { messages: [{ role: 'user', content: input }] };
	}
	if (Array.isArray(input)) {
		return { messages: [...input] };
	}
	return { messages: [...input.messages], tools: input.tools, system: input.system };
}

function collectDeclaredToolNames(tools: ToolDef[] | undefined): Set<string> {
	const names = new Set<string>();
	if (tools) for (const t of tools) names.add(t.name);
	return names;
}

function errorInfo(err: unknown): { name: string; message: string } {
	if (err instanceof Error) {
		return { name: err.name, message: err.message };
	}
	// Some thrown values are plain objects with a `message` field but no Error chain —
	// e.g. Harper's `BigInt.prototype.toJSON` throws `{message: 'Cannot serialize BigInt …'}`
	// (server/serverHelpers/JSONStream.ts) to skip the cost of capturing a stack on a hot
	// serialization path. Surface their message instead of String()-ing the whole object.
	if (err && typeof err === 'object' && 'message' in err) {
		const e = err as { name?: unknown; message?: unknown };
		const name = typeof e.name === 'string' ? e.name : 'Error';
		const message = typeof e.message === 'string' ? e.message : String(e.message);
		return { name, message };
	}
	return { name: 'Error', message: String(err) };
}

interface SerializedResult {
	content: string;
	totalBytes: number;
	truncated: boolean;
}

function serializeToolResult(value: unknown, maxBytes: number): SerializedResult {
	// `JSON.stringify(Symbol())` (and `JSON.stringify(function(){})`) return `undefined`.
	// `value ?? null` only catches null/undefined inputs, not unsupported types — fall
	// back to the string 'null' so downstream `Buffer.byteLength` never sees undefined.
	const json = JSON.stringify(value ?? null) ?? 'null';
	const totalBytes = Buffer.byteLength(json, 'utf8');
	// Common case: result fits. Skip buffer allocation entirely — read byte length
	// without materializing a copy.
	if (totalBytes <= maxBytes) {
		return { content: json, totalBytes, truncated: false };
	}
	// Truncated form: head of the JSON + a marker that names the original size. The
	// content is no longer valid JSON — that's intentional, the model reads it as text
	// alongside the marker. Pre-slice the JSON string by CHARACTERS to `headBudget`
	// before converting to a Buffer — any character takes at least one UTF-8 byte, so
	// the pre-sliced string already fits in (4 * headBudget) bytes worst-case. Without
	// this, a multi-MB JSON result would materialize a multi-MB Buffer copy just to
	// throw away >99 % of it via `subarray`. After conversion, `subarray(0, headBudget)`
	// trims to exact byte budget; `toString('utf8')` folds a split codepoint at the
	// boundary into U+FFFD.
	const marker = `…[truncated; full result is ${totalBytes} bytes]`;
	const markerBytes = Buffer.byteLength(marker, 'utf8');
	const headBudget = Math.max(0, maxBytes - markerBytes);
	const buf = Buffer.from(json.slice(0, headBudget), 'utf8');
	const body = buf.subarray(0, headBudget).toString('utf8');
	return { content: body + marker, totalBytes, truncated: true };
}

/**
 * Loop tripped one of its budgets (iterations, tokens, cost). The trace built so
 * far rides along on `partialTrace` so callers can inspect what already ran. The
 * loop always populates this regardless of `opts.includeToolTrace` so debugging an
 * exhausted budget never needs a second run with tracing turned on.
 *
 * Extends `ClientError` — the caller set the budget, so exceeding it is a 4xx
 * caller-bounds condition, not a Harper-internal fault. Anything that branches on
 * `err instanceof ClientError` (e.g. "don't page on this") classifies it correctly.
 */
export class BudgetExceededError extends ClientError {
	kind: 'iterations' | 'tokens' | 'cost';
	partialTrace: ToolTraceEntry[];
	constructor(kind: 'iterations' | 'tokens' | 'cost', message: string, partialTrace: ToolTraceEntry[]) {
		// 429 (Too Many Requests) maps cleanest to "you exceeded the budget you set".
		super(message, 429);
		this.name = 'BudgetExceededError';
		this.kind = kind;
		this.partialTrace = partialTrace;
	}
}

/**
 * Surfaced under `toolErrorMode: 'abort'` when a tool handler throws (or its
 * result fails to serialize). Carries the original throw on `.cause` and the
 * partial trace — including the failing entry — on `.partialTrace` so callers
 * always have the full picture on the abort path.
 *
 * `statusCode` mirrors the underlying error when it carries one (e.g. a handler
 * throwing `ClientError(400)` surfaces as `ToolHandlerError(400)`), otherwise
 * defaults to 500.
 *
 * **`instanceof` caveat:** extends `ServerError` regardless of `statusCode`, so a
 * handler-thrown `ClientError(403)` becomes a `ToolHandlerError` whose `statusCode`
 * is 403 but where `instanceof ClientError === false`. Callers that route on
 * client-vs-server class should branch on `err.statusCode` or
 * `err.cause instanceof ClientError`, not on `err instanceof ClientError` directly.
 */
export class ToolHandlerError extends ServerError {
	toolName: string;
	toolCallId: string;
	partialTrace: ToolTraceEntry[];
	constructor(toolName: string, toolCallId: string, partialTrace: ToolTraceEntry[], cause: unknown) {
		const causeMessage = errorInfo(cause).message;
		const causeStatus =
			cause &&
			typeof cause === 'object' &&
			'statusCode' in cause &&
			typeof (cause as { statusCode: unknown }).statusCode === 'number'
				? (cause as { statusCode: number }).statusCode
				: 500;
		super(`Tool handler '${toolName}' (call ${toolCallId}) failed: ${causeMessage}`, causeStatus);
		this.name = 'ToolHandlerError';
		this.toolName = toolName;
		this.toolCallId = toolCallId;
		this.partialTrace = partialTrace;
		this.cause = cause;
	}
}

/**
 * Cost computation hook. v1 returns 0 — no per-model rate card is wired today —
 * so `maxCostUsd` never trips in production. The cap, the trip path, and the
 * `BudgetExceededError({kind: 'cost'})` shape ARE wired and exercised by tests
 * that inject a non-zero function via `_setComputeCallCostUsdForTests`. When the
 * rate card lands, replace this implementation; no surface change needed.
 */
let computeCallCostUsd: (usage: TokenUsage | undefined, model: string | undefined) => number = () => 0;

/**
 * Test-only override. Public callers must not depend on this — it exists so unit
 * tests can prove the `maxCostUsd` trip path works end-to-end before a real rate
 * card lands. Leading underscore marks the intent.
 */
export function _setComputeCallCostUsdForTests(
	fn: (usage: TokenUsage | undefined, model: string | undefined) => number
): void {
	computeCallCostUsd = fn;
}

/**
 * Reset the cost function to the v1 stub. Pair with `_setComputeCallCostUsdForTests`
 * in test `afterEach` so suites don't leak state into each other.
 */
export function _resetComputeCallCostUsdForTests(): void {
	computeCallCostUsd = () => 0;
}

function sumTokens(usage: TokenUsage | undefined): number {
	if (!usage) return 0;
	let total = 0;
	if (typeof usage.promptTokens === 'number' && usage.promptTokens > 0) total += usage.promptTokens;
	if (typeof usage.completionTokens === 'number' && usage.completionTokens > 0) total += usage.completionTokens;
	return total;
}

/**
 * `toolArgValidation: 'strict'` rejected a tool call's arguments against its
 * declared `parameters` JSON Schema. Surfaces as a 400 — the model produced output
 * that doesn't satisfy the contract the caller declared. Reserved for the
 * validator wiring (currently the strict mode is itself gated at loop entry).
 */
export class ToolValidationError extends ClientError {
	toolName: string;
	toolCallId: string;
	validationErrors: object[];
	constructor(toolName: string, toolCallId: string, validationErrors: object[], message: string) {
		super(message, 400);
		this.name = 'ToolValidationError';
		this.toolName = toolName;
		this.toolCallId = toolCallId;
		this.validationErrors = validationErrors;
	}
}