experimental-a2 0.0.0 → 0.2.0

package/dist/ai-server.js

@@ -1,12 +1,286 @@
-import { t as createServer } from "./server-DYsnKTTy.js";
-import { ToolLoopAgent, createAgentUIStream } from "ai";
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { t as createServer } from "./server-DJgD2YWP.js";
+import { convertToModelMessages, stepCountIs, streamText, toUIMessageStream } from "ai";
+//#region src/ai-sdk-step.ts
+const CONTROLLED_SETTINGS = [
+	"_internal",
+	"abortSignal",
+	"instructions",
+	"messages",
+	"model",
+	"onToolExecutionEnd",
+	"onToolExecutionStart",
+	"experimental_onToolCallFinish",
+	"experimental_onToolCallStart",
+	"experimental_sandbox",
+	"experimental_toolCallers",
+	"experimental_toolApprovalSecret",
+	"prompt",
+	"prepareStep",
+	"stopWhen",
+	"system",
+	"tools",
+	"toolsContext"
+];
+const safeSettings = (settings) => {
+	const result = { ...settings };
+	for (const key of CONTROLLED_SETTINGS) Reflect.deleteProperty(result, key);
+	if (typeof result.timeout === "object" && result.timeout !== null) {
+		const timeout = { ...result.timeout };
+		Reflect.deleteProperty(timeout, "toolMs");
+		Reflect.deleteProperty(timeout, "tools");
+		result.timeout = timeout;
+	}
+	return result;
+};
+const modelToolSet = (tools) => Object.fromEntries(Object.entries(tools).map(([name, tool]) => {
+	if (tool.type === "provider" && tool.isProviderExecuted === true) return [name, tool];
+	const definition = { ...tool };
+	Reflect.deleteProperty(definition, "execute");
+	return [name, definition];
+}));
+const errorMessage$1 = (error) => error instanceof Error ? error.message : String(error);
+/** Run exactly one AI SDK model step while leaving local tool execution to A2. */
+async function generateAISDKStep(input) {
+	const settings = safeSettings(input.settings);
+	const tools = modelToolSet(input.tools);
+	const messages = await convertToModelMessages(input.messages, { tools });
+	const streamOptions = {
+		...settings,
+		model: input.model,
+		tools,
+		messages,
+		abortSignal: input.abortSignal,
+		...input.instructions === void 0 ? {} : { instructions: input.instructions },
+		stopWhen: stepCountIs(1),
+		onError: settings.onError ?? (() => {})
+	};
+	const result = streamText(streamOptions);
+	let completion;
+	let fatalError;
+	const observed = result.stream.pipeThrough(new TransformStream({ transform(part, controller) {
+		if (part.type === "error" && fatalError === void 0) fatalError = { value: part.error };
+		else if (part.type === "finish") completion = {
+			finishReason: part.finishReason,
+			usage: part.totalUsage
+		};
+		controller.enqueue(part);
+	} }));
+	return {
+		stream: toUIMessageStream({
+			stream: observed,
+			tools,
+			originalMessages: input.messages,
+			generateMessageId: () => input.responseMessageId,
+			onError: errorMessage$1
+		}),
+		completion() {
+			if (fatalError !== void 0) throw fatalError.value;
+			if (completion === void 0) throw new Error("AI SDK step ended without a finish part");
+			if (completion.finishReason === "error") throw new Error("AI SDK step finished with an error");
+			return completion;
+		}
+	};
+}
+//#endregion
+//#region src/ai-coordinator.ts
+const updateResponse = (state, update) => state.response === void 0 ? state : {
+	...state,
+	response: update(state.response)
+};
+const foldCoordinator = (state, event) => {
+	switch (event.type) {
+		case "ai.session.closed": return {
+			closed: true,
+			queued: []
+		};
+		case "ai.message.created": {
+			const message = event.payload.message;
+			if (message.role !== "user") return state;
+			return {
+				...state,
+				queued: [...state.queued.filter((item) => item.messageId !== message.id), {
+					index: event.index,
+					messageId: message.id
+				}].toSorted((left, right) => left.index - right.index)
+			};
+		}
+		case "ai.generation.requested": {
+			const request = event.payload;
+			if (request.reason === "message") {
+				const responseMessageId = request.responseMessageId ?? `${request.messageId}:assistant`;
+				return {
+					...state,
+					queued: state.queued.filter((item) => item.messageId !== request.messageId),
+					response: {
+						rootMessageId: request.messageId,
+						responseMessageId,
+						status: "requested",
+						activeRequestId: event.id,
+						calls: [],
+						inputs: []
+					}
+				};
+			}
+			if (state.response === void 0 || request.responseMessageId !== state.response.responseMessageId) return state;
+			if (request.reason === "tool" && (!continuationReady(state) || event.id !== `ai.generate:tools:${state.response.generation?.generationId}`) || request.reason === "retry" && state.response.status !== "failed" || request.reason === "input" && state.response.inputResponse === void 0) return state;
+			return updateResponse(state, (response) => ({
+				rootMessageId: response.rootMessageId,
+				responseMessageId: response.responseMessageId,
+				status: "requested",
+				activeRequestId: event.id,
+				calls: [],
+				inputs: []
+			}));
+		}
+		case "ai.generation.started": {
+			const generation = event.payload;
+			if (state.response?.responseMessageId !== generation.responseMessageId || state.response.activeRequestId !== generation.requestId || state.response.generation?.requestId === generation.requestId && state.response.generation.attempt >= generation.attempt) return state;
+			return updateResponse(state, (response) => ({
+				rootMessageId: response.rootMessageId,
+				responseMessageId: response.responseMessageId,
+				status: "generating",
+				generation,
+				activeRequestId: generation.requestId,
+				calls: [],
+				inputs: []
+			}));
+		}
+		case "ai.generation.completed": {
+			const completion = event.payload;
+			if (state.response?.generation?.generationId !== completion.generationId) return state;
+			return updateResponse(state, (response) => ({
+				...response,
+				status: "waiting",
+				completion
+			}));
+		}
+		case "ai.generation.failed": {
+			const failure = event.payload;
+			const response = state.response;
+			const ownsActiveGeneration = response?.generation?.generationId === failure.generationId;
+			const ownsActiveStepLimit = failure.stepLimit === true && response?.activeRequestId === `ai.generate:tools:${failure.generationId}` && response.responseMessageId === failure.responseMessageId;
+			if (!ownsActiveGeneration && !ownsActiveStepLimit) return state;
+			return updateResponse(state, (current) => ({
+				...current,
+				status: "failed",
+				failure
+			}));
+		}
+		case "ai.message.completed": {
+			const messageId = event.payload.messageId;
+			return state.response?.responseMessageId === messageId ? {
+				closed: state.closed,
+				queued: state.queued
+			} : state;
+		}
+		case "ai.message.interrupted": {
+			const interruption = event.payload;
+			const response = state.response;
+			return response?.responseMessageId === interruption.messageId && (interruption.generationId === void 0 || interruption.generationId === response.generation?.generationId) ? {
+				closed: state.closed,
+				queued: state.queued
+			} : state;
+		}
+		case "ai.tool.called": {
+			const call = event.payload;
+			if (state.response?.generation?.generationId !== call.generationId) return state;
+			return updateResponse(state, (response) => ({
+				...response,
+				calls: [...response.calls.filter((candidate) => candidate.call.toolCallId !== call.toolCallId), {
+					index: event.index,
+					call,
+					terminal: false
+				}]
+			}));
+		}
+		case "ai.approval.requested": {
+			const approval = event.payload;
+			if (state.response?.generation?.generationId !== approval.generationId) return state;
+			return updateResponse(state, (response) => ({
+				...response,
+				calls: response.calls.map((candidate) => candidate.call.toolCallId === approval.toolCallId ? {
+					...candidate,
+					approval
+				} : candidate)
+			}));
+		}
+		case "ai.approval.responded": {
+			const approval = event.payload;
+			if (state.response?.responseMessageId !== approval.messageId || state.response.generation?.generationId !== approval.generationId) return state;
+			return updateResponse(state, (response) => ({
+				...response,
+				calls: response.calls.map((candidate) => candidate.approval?.approvalId === approval.approvalId ? {
+					...candidate,
+					response: approval,
+					responseIndex: event.index
+				} : candidate)
+			}));
+		}
+		case "ai.tool.result": {
+			const result = event.payload;
+			if (result.preliminary === true || state.response?.generation?.generationId !== result.generationId) return state;
+			return updateResponse(state, (response) => ({
+				...response,
+				calls: response.calls.map((candidate) => candidate.call.toolCallId === result.toolCallId ? {
+					...candidate,
+					terminal: true
+				} : candidate)
+			}));
+		}
+		case "ai.input.requested": {
+			const input = event.payload;
+			if (state.response?.responseMessageId !== input.messageId || state.response.generation?.generationId !== input.generationId) return state;
+			return updateResponse(state, (response) => ({
+				...response,
+				inputs: [...response.inputs.filter((candidate) => candidate.messageId !== input.messageId || candidate.generationId !== input.generationId || candidate.inputId !== input.inputId), input]
+			}));
+		}
+		case "ai.input.responded": {
+			const input = event.payload;
+			const requested = state.response?.inputs.find((candidate) => candidate.messageId === input.messageId && candidate.generationId === input.generationId && candidate.inputId === input.inputId && candidate.name === input.name);
+			if (state.response?.responseMessageId !== input.messageId || state.response.generation?.generationId !== input.generationId || requested === void 0) return state;
+			return updateResponse(state, (response) => ({
+				...response,
+				inputs: response.inputs.filter((candidate) => candidate.inputId !== input.inputId),
+				inputResponse: {
+					index: event.index,
+					generationId: input.generationId,
+					inputId: input.inputId,
+					name: requested.name
+				}
+			}));
+		}
+		default: return state;
+	}
+};
+const aiCoordinatorReducer = (contract) => contract.reducer({
+	name: "a2.ai.coordinator.v1",
+	initialState: {
+		closed: false,
+		queued: []
+	}
+}).fold((state, event) => foldCoordinator(state, event));
+const continuationReady = (state) => {
+	const response = state.response;
+	return !state.closed && response?.completion?.finishReason === "tool-calls" && response.generation?.generationId === response.completion.generationId && response.failure === void 0 && response.calls.length > 0 && response.calls.every((call) => call.terminal || call.call.providerExecuted === true && call.call.supportsDeferredResults !== true && call.approval !== void 0 && call.response !== void 0);
+};
+//#endregion
 //#region src/ai-server.ts
 /**
-* a2/ai/server — the server-only implementation of an a2/ai definition.
+* experimental-a2/ai/server — the server-only implementation of an experimental-a2/ai definition.
 *
 * `createHandlers()` exposes the ordinary A2 handler table;
 * `createAgentServer()` is its batteries-included assembly with createServer.
 */
+function validateAgentPush(context) {
+	const rejected = context.events.find((event) => {
+		if (event.type !== "ai.message.created") return !(event.type === "ai.approval.responded" || event.type === "ai.input.responded" || event.type === "ai.message.interrupted" || event.type === "ai.retry.requested");
+		const payload = event.payload;
+		return typeof payload !== "object" || payload === null || !("message" in payload) || typeof payload.message !== "object" || payload.message === null || !("role" in payload.message) || payload.message.role !== "user";
+	});
+	if (rejected !== void 0) throw new A2Error("INVALID_PAYLOAD", `event '${rejected.type}' is server-only for an AI agent`);
+}
 const resolve = async (value, context) => typeof value === "function" ? await value(context) : value;
 const modelName = (model) => {
 	if (typeof model === "string") return model;
@@ -14,23 +288,8 @@ const modelName = (model) => {
 	return "custom";
 };
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
-const addTokenCounts = (left, right) => left === void 0 && right === void 0 ? void 0 : (left ?? 0) + (right ?? 0);
-const addUsage = (left, right) => {
-	return {
-		inputTokens: addTokenCounts(left?.inputTokens, right.inputTokens),
-		inputTokenDetails: {
-			noCacheTokens: addTokenCounts(left?.inputTokenDetails.noCacheTokens, right.inputTokenDetails.noCacheTokens),
-			cacheReadTokens: addTokenCounts(left?.inputTokenDetails.cacheReadTokens, right.inputTokenDetails.cacheReadTokens),
-			cacheWriteTokens: addTokenCounts(left?.inputTokenDetails.cacheWriteTokens, right.inputTokenDetails.cacheWriteTokens)
-		},
-		outputTokens: addTokenCounts(left?.outputTokens, right.outputTokens),
-		outputTokenDetails: {
-			textTokens: addTokenCounts(left?.outputTokenDetails.textTokens, right.outputTokenDetails.textTokens),
-			reasoningTokens: addTokenCounts(left?.outputTokenDetails.reasoningTokens, right.outputTokenDetails.reasoningTokens)
-		},
-		totalTokens: addTokenCounts(left?.totalTokens, right.totalTokens)
-	};
-};
+const promptCacheKey = (sessionId, generationId) => `${sessionId}\u001f${generationId}`;
+const isAsyncIterable = (value) => typeof value === "object" && value !== null && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === "function";
 const isBoundaryChunk = (chunk) => chunk !== void 0 && (chunk.type === "text-end" || chunk.type === "reasoning-end" || chunk.type === "tool-input-available" || chunk.type === "tool-input-error" || chunk.type === "tool-output-available" || chunk.type === "tool-output-error" || chunk.type === "tool-output-denied" || chunk.type === "tool-approval-request" || chunk.type === "finish" || chunk.type === "abort" || chunk.type === "error");
 const nextOrTimer = async (next, delayMs) => {
 	let timer;
@@ -47,41 +306,24 @@ const nextOrTimer = async (next, delayMs) => {
 	}
 };
 async function generateWithAISDK(context) {
-	const { onStepEnd, onStepFinish, ...settings } = context.generation;
-	const userOnStepEnd = onStepEnd ?? onStepFinish;
-	const agentSettings = {
-		...settings,
-		id: context.generationId,
+	const step = await generateAISDKStep({
 		model: context.model,
 		tools: context.tools,
-		...context.instructions === void 0 ? {} : { instructions: context.instructions }
-	};
-	const sdkAgent = new ToolLoopAgent(agentSettings);
-	let usage;
-	let finishReason;
+		messages: context.messages,
+		responseMessageId: context.responseMessageId,
+		abortSignal: context.signal,
+		...context.instructions === void 0 ? {} : { instructions: context.instructions },
+		settings: context.generation
+	});
 	return {
-		stream: await createAgentUIStream({
-			agent: sdkAgent,
-			uiMessages: context.messages,
-			generateMessageId: () => context.responseMessageId,
-			abortSignal: context.signal,
-			async onStepEnd(step) {
-				usage = addUsage(usage, step.usage);
-				await userOnStepEnd?.(step);
-			},
-			onEnd(event) {
-				finishReason = event.finishReason;
-			}
-		}),
-		completion: () => ({
-			...finishReason === void 0 ? {} : { finishReason },
-			...usage === void 0 ? {} : { usage }
-		})
+		stream: step.stream,
+		completion: step.completion
 	};
 }
 async function* consumeGeneration(options) {
 	const pending = [];
 	let streamedFinishReason;
+	let streamedError;
 	const maxChunks = options.progress?.maxChunks ?? 16;
 	const maxDelayMs = options.progress?.maxDelayMs ?? 30;
 	let lastFlush = Date.now();
@@ -107,6 +349,7 @@ async function* consumeGeneration(options) {
 			const chunk = result.value;
 			pending.push(chunk);
 			if (chunk.type === "finish") streamedFinishReason = chunk.finishReason;
+			if (chunk.type === "error") streamedError = chunk.errorText;
 			pendingChunk = chunks.next();
 			if (pending.length >= maxChunks || isBoundaryChunk(pending.at(-1))) {
 				yield {
@@ -123,11 +366,21 @@ async function* consumeGeneration(options) {
 		};
 		throw error;
 	}
-	const completion = options.source.completion?.();
+	let completion;
+	try {
+		completion = options.source.completion?.();
+	} catch (error) {
+		if (pending.length > 0) yield {
+			type: "progress",
+			chunks: pending.splice(0)
+		};
+		throw error;
+	}
 	if (pending.length > 0) yield {
 		type: "progress",
 		chunks: pending.splice(0)
 	};
+	if (streamedError !== void 0) throw new Error(streamedError);
 	const finishReason = completion?.finishReason ?? streamedFinishReason;
 	yield {
 		type: "finish",
@@ -144,10 +397,45 @@ const contextMessages = (state) => {
 	const compaction = state.compaction;
 	if (compaction?.status !== "completed" || !compaction.messages) return state.messages;
 	const boundary = state.messages.findIndex((message) => message.id === compaction.throughMessageId);
-	return boundary === -1 ? state.messages : [...compaction.messages, ...state.messages.slice(boundary + 1)];
+	const retained = new Set(compaction.retainedMessageIds ?? []);
+	return boundary === -1 ? state.messages : [
+		...compaction.messages,
+		...state.messages.slice(0, boundary + 1).filter((message) => retained.has(message.id)),
+		...state.messages.slice(boundary + 1)
+	];
+};
+const activeContextMessages = (state, coordinator) => {
+	const queued = new Set(coordinator.queued.map((item) => item.messageId));
+	return contextMessages(state).filter((message) => !queued.has(message.id));
+};
+const toolCalledEvent = (payload) => ({
+	type: "ai.tool.called",
+	id: `${payload.generationId}:tool:${payload.toolCallId}:called`,
+	payload
+});
+const approvalClassification = (tools, generation, toolName) => {
+	const configured = generation.toolApproval;
+	if (typeof configured === "function") return "unknown";
+	const policy = configured?.[toolName];
+	if (typeof policy === "function") return "unknown";
+	if (policy === "user-approval" || typeof policy === "object" && policy?.type === "user-approval") return "approval";
+	if (policy === "denied" || typeof policy === "object" && policy?.type === "denied") return "approval";
+	const tool = tools[toolName];
+	if (typeof tool?.needsApproval === "function") return "unknown";
+	return tool?.needsApproval === true ? "approval" : "automatic";
 };
 const lifecycleEvents = (options) => {
 	const result = [];
+	const pending = [...options.pending];
+	const take = (toolCallId) => {
+		const index = pending.findIndex((candidate) => candidate.call.toolCallId === toolCallId);
+		if (index === -1) return void 0;
+		return pending.splice(index, 1)[0];
+	};
+	const flush = (toolCallId) => {
+		const pendingCall = take(toolCallId);
+		if (pendingCall) result.push(toolCalledEvent(pendingCall.call));
+	};
 	for (const [chunkIndex, chunk] of options.chunks.entries()) {
 		const resultId = `${options.generationId}:tool-result:${options.sequence}:${chunkIndex}`;
 		if (chunk.type === "tool-input-available") {
@@ -160,14 +448,17 @@ const lifecycleEvents = (options) => {
 				input: chunk.input,
 				...chunk.dynamic === void 0 ? {} : { dynamic: chunk.dynamic },
 				...chunk.providerExecuted === void 0 ? {} : { providerExecuted: chunk.providerExecuted },
+				...options.tools[chunk.toolName]?.supportsDeferredResults === true ? { supportsDeferredResults: true } : {},
 				...chunk.providerMetadata === void 0 ? {} : { providerMetadata: chunk.providerMetadata },
 				...chunk.toolMetadata === void 0 ? {} : { toolMetadata: chunk.toolMetadata },
 				...chunk.title === void 0 ? {} : { title: chunk.title }
 			};
-			result.push({
-				type: "ai.tool.called",
-				id: `${options.generationId}:tool:${chunk.toolCallId}:called`,
-				payload
+			take(payload.toolCallId);
+			const classification = approvalClassification(options.tools, options.generation, chunk.toolName);
+			if (classification === "automatic") result.push(toolCalledEvent(payload));
+			else pending.push({
+				call: payload,
+				classification
 			});
 		} else if (chunk.type === "tool-input-error") {
 			const payload = {
@@ -184,12 +475,22 @@ const lifecycleEvents = (options) => {
 				...chunk.providerMetadata === void 0 ? {} : { providerMetadata: chunk.providerMetadata },
 				...chunk.toolMetadata === void 0 ? {} : { toolMetadata: chunk.toolMetadata }
 			};
-			result.push({
+			const called = {
+				requestId: options.requestId,
+				messageId: options.messageId,
+				generationId: options.generationId,
+				toolCallId: chunk.toolCallId,
+				toolName: chunk.toolName,
+				input: chunk.input
+			};
+			take(chunk.toolCallId);
+			result.push(toolCalledEvent(called), {
 				type: "ai.tool.result",
 				id: resultId,
 				payload
 			});
 		} else if (chunk.type === "tool-output-available") {
+			flush(chunk.toolCallId);
 			const payload = {
 				requestId: options.requestId,
 				messageId: options.messageId,
@@ -209,6 +510,7 @@ const lifecycleEvents = (options) => {
 				payload
 			});
 		} else if (chunk.type === "tool-output-error") {
+			flush(chunk.toolCallId);
 			const payload = {
 				requestId: options.requestId,
 				messageId: options.messageId,
@@ -227,6 +529,7 @@ const lifecycleEvents = (options) => {
 				payload
 			});
 		} else if (chunk.type === "tool-output-denied") {
+			flush(chunk.toolCallId);
 			const payload = {
 				requestId: options.requestId,
 				messageId: options.messageId,
@@ -241,6 +544,7 @@ const lifecycleEvents = (options) => {
 				payload
 			});
 		} else if (chunk.type === "tool-approval-request") {
+			flush(chunk.toolCallId);
 			const payload = {
 				messageId: options.messageId,
 				generationId: options.generationId,
@@ -254,10 +558,52 @@ const lifecycleEvents = (options) => {
 				id: `${options.generationId}:approval:${chunk.approvalId}`,
 				payload
 			});
-		}
+		} else if (chunk.type === "tool-approval-response") result.push({
+			type: "ai.approval.responded",
+			id: `${options.generationId}:approval:${chunk.approvalId}:automatic-response`,
+			payload: {
+				messageId: options.messageId,
+				generationId: options.generationId,
+				approvalId: chunk.approvalId,
+				approved: chunk.approved,
+				...chunk.reason === void 0 ? {} : { reason: chunk.reason }
+			}
+		});
 	}
-	return result;
+	return {
+		events: result,
+		pending
+	};
 };
+function queuedMessagesAt(history) {
+	const started = new Set(history.filter((event) => event.type === "ai.generation.requested").map((event) => event.payload).filter((request) => request.reason === "message").map((request) => request.messageId));
+	return history.flatMap((event) => {
+		if (event.type !== "ai.message.created") return [];
+		const message = event.payload.message;
+		return message.role === "user" && !started.has(message.id) ? [{
+			index: event.index,
+			messageId: message.id
+		}] : [];
+	});
+}
+function withoutGenerationLifecycle(history, generationIds) {
+	if (generationIds.size === 0) return history;
+	const approvalKeys = /* @__PURE__ */ new Set();
+	const inputKeys = /* @__PURE__ */ new Set();
+	for (const event of history) {
+		const payload = event.payload;
+		if (typeof payload.generationId !== "string" || !generationIds.has(payload.generationId) || typeof payload.messageId !== "string") continue;
+		if (event.type === "ai.approval.requested" && typeof payload.approvalId === "string") approvalKeys.add(`${payload.messageId}\u001f${payload.approvalId}`);
+		if (event.type === "ai.input.requested" && typeof payload.inputId === "string") inputKeys.add(`${payload.messageId}\u001f${payload.inputId}`);
+	}
+	return history.filter((event) => {
+		const payload = event.payload;
+		if (typeof payload.generationId === "string" && generationIds.has(payload.generationId)) return false;
+		if (event.type === "ai.approval.responded" && typeof payload.messageId === "string" && typeof payload.approvalId === "string") return !approvalKeys.has(`${payload.messageId}\u001f${payload.approvalId}`);
+		if (event.type === "ai.input.responded" && typeof payload.messageId === "string" && typeof payload.inputId === "string") return !inputKeys.has(`${payload.messageId}\u001f${payload.inputId}`);
+		return true;
+	});
+}
 /**
 * Build the ordinary A2 handler table for the built-in agent protocol.
 * Application handlers can be spread beside this table.
@@ -266,11 +612,161 @@ function createHandlers(options) {
 	if (options.model === void 0) throw new TypeError("createHandlers requires model");
 	if (options.progress?.maxChunks !== void 0 && (!Number.isInteger(options.progress.maxChunks) || options.progress.maxChunks < 1)) throw new TypeError("progress.maxChunks must be a positive integer");
 	if (options.progress?.maxDelayMs !== void 0 && (!Number.isFinite(options.progress.maxDelayMs) || options.progress.maxDelayMs < 0)) throw new TypeError("progress.maxDelayMs must be a non-negative number");
+	if (options.maxSteps !== void 0 && (!Number.isInteger(options.maxSteps) || options.maxSteps < 1)) throw new TypeError("maxSteps must be a positive integer");
+	const tools = options.tools ?? {};
+	const generation = options.generation ?? {};
+	const maxSteps = options.maxSteps ?? 20;
+	const coordinator = aiCoordinatorReducer(options.agent.contract);
+	const promptCache = /* @__PURE__ */ new Map();
+	const coordinatorStateAt = (history, frontier = Number.POSITIVE_INFINITY) => {
+		let state = coordinator.initialState;
+		for (const event of history) {
+			if (event.index >= frontier) break;
+			state = coordinator.fold(state, event);
+		}
+		return state;
+	};
+	const requestForNextMessage = (state) => {
+		if (state.closed || state.response !== void 0) return void 0;
+		const next = state.queued[0];
+		if (next === void 0) return void 0;
+		return {
+			type: "ai.generation.requested",
+			id: `ai.generate:message:${next.messageId}`,
+			payload: {
+				messageId: next.messageId,
+				reason: "message"
+			}
+		};
+	};
+	const scheduleNext = async (ctx) => requestForNextMessage((await ctx.session.state(coordinator)).state);
+	const continueIfReady = async (ctx, generationId) => {
+		const state = (await ctx.session.state(coordinator)).state;
+		const response = state.response;
+		if (response?.generation?.generationId !== generationId) return;
+		const input = response.inputResponse;
+		if (response.completion?.generationId === generationId && response.failure === void 0 && input !== void 0 && response.inputs.length === 0 && response.calls.every((call) => call.terminal || call.call.providerExecuted === true && call.call.supportsDeferredResults !== true && call.approval !== void 0 && call.response !== void 0)) {
+			await ctx.session.append("continue-after-input", {
+				type: "ai.generation.requested",
+				id: `ai.generate:input:${encodeURIComponent(response.responseMessageId)}:${encodeURIComponent(input.generationId)}:${encodeURIComponent(input.inputId)}`,
+				payload: {
+					messageId: response.responseMessageId,
+					responseMessageId: response.responseMessageId,
+					reason: "input"
+				}
+			});
+			return;
+		}
+		if (!continuationReady(state)) return;
+		await ctx.session.append("continue-after-tools", {
+			type: "ai.generation.requested",
+			id: `ai.generate:tools:${generationId}`,
+			payload: {
+				messageId: response.responseMessageId,
+				responseMessageId: response.responseMessageId,
+				reason: "tool"
+			}
+		});
+	};
+	const resultEvent = (call, suffix, result) => ({
+		type: "ai.tool.result",
+		id: `${call.generationId}:tool:${call.toolCallId}:${suffix}`,
+		payload: {
+			requestId: call.requestId,
+			messageId: call.messageId,
+			generationId: call.generationId,
+			toolCallId: call.toolCallId,
+			toolName: call.toolName,
+			input: call.input,
+			phase: "execution",
+			...result.output === void 0 ? {} : { output: result.output },
+			...result.error === void 0 ? {} : { error: result.error },
+			...result.denied === void 0 ? {} : { denied: result.denied },
+			...result.preliminary === void 0 ? {} : { preliminary: result.preliminary },
+			...call.dynamic === void 0 ? {} : { dynamic: call.dynamic },
+			...call.providerExecuted === void 0 ? {} : { providerExecuted: call.providerExecuted },
+			...call.toolMetadata === void 0 ? {} : { toolMetadata: call.toolMetadata }
+		}
+	});
+	const promptMessages = (sessionId, call, readHistory) => {
+		const key = promptCacheKey(sessionId, call.generationId);
+		const cached = promptCache.get(key);
+		if (cached) return cached;
+		const computation = (async () => {
+			const history = await readHistory();
+			const coordinatorState = coordinatorStateAt(history);
+			const compaction = history.find((event) => event.type === "ai.compaction.completed" && event.payload.generationId === call.generationId);
+			if (compaction !== void 0) {
+				const messages = compaction.payload.messages.filter((message) => !coordinatorState.queued.some((queued) => queued.messageId === message.id));
+				return convertToModelMessages(messages, { tools });
+			}
+			const frontier = history.find((event) => event.type === "ai.generation.started" && event.payload.generationId === call.generationId)?.index ?? Number.POSITIVE_INFINITY;
+			const state = replay(options.agent, history.filter((event) => event.index < frontier));
+			return convertToModelMessages(activeContextMessages(state, coordinatorState), { tools });
+		})();
+		promptCache.set(key, computation);
+		computation.catch(() => {
+			if (promptCache.get(key) === computation) promptCache.delete(key);
+		});
+		return computation;
+	};
+	const executeTool = async (ctx, call) => {
+		const tool = tools[call.toolName];
+		if (tool?.execute === void 0) return resultEvent(call, "execution:error", { error: `Tool '${call.toolName}' has no server executor` });
+		const messages = await promptMessages(ctx.event.sessionId, call, ctx.session.history);
+		let output;
+		try {
+			output = await tool.execute(call.input, {
+				toolCallId: call.toolCallId,
+				messages,
+				abortSignal: ctx.signal,
+				context: void 0
+			});
+		} catch (error) {
+			if (ctx.signal.aborted) return;
+			return resultEvent(call, "execution:error", { error: errorMessage(error) });
+		}
+		if (!isAsyncIterable(output)) return resultEvent(call, "execution:0", { output });
+		let last;
+		let sequence = 0;
+		for await (const value of output) {
+			if (ctx.signal.aborted) return;
+			last = value;
+			await ctx.session.append(`tool:${call.toolCallId}:preliminary:${sequence}`, resultEvent(call, `execution:${sequence}:preliminary`, {
+				output: value,
+				preliminary: true
+			}));
+			sequence += 1;
+		}
+		return resultEvent(call, `execution:${sequence}:final`, sequence === 0 ? {} : { output: last });
+	};
+	const handleToolCall = async (ctx) => {
+		const response = (await ctx.session.state(coordinator)).state.response;
+		const current = response?.calls.find((candidate) => candidate.index === ctx.event.index);
+		if (current === void 0 || response?.generation?.generationId !== ctx.event.payload.generationId || response.failure !== void 0 || current.terminal || current.approval !== void 0) return;
+		if (current.call.providerExecuted === true) {
+			await continueIfReady(ctx, current.call.generationId);
+			return;
+		}
+		return executeTool(ctx, current.call);
+	};
+	const handleApproval = async (ctx) => {
+		const response = (await ctx.session.state(coordinator)).state.response;
+		const current = response?.calls.find((candidate) => candidate.approval?.approvalId === ctx.event.payload.approvalId && candidate.approval.messageId === ctx.event.payload.messageId && candidate.approval.generationId === ctx.event.payload.generationId && candidate.responseIndex === ctx.event.index);
+		if (current === void 0 || response?.generation?.generationId !== current.call.generationId || response.failure !== void 0 || current.terminal) return;
+		if (current.call.providerExecuted === true) {
+			await continueIfReady(ctx, current.call.generationId);
+			return;
+		}
+		if (!ctx.event.payload.approved) return resultEvent(current.call, "execution:denied", { denied: true });
+		return executeTool(ctx, current.call);
+	};
 	const generationHandler = async (ctx) => {
-		const history = await ctx.history();
+		const history = await ctx.session.history();
 		const requestId = ctx.event.id;
 		const request = ctx.event.payload;
-		if (history.some((event) => event.type === "ai.session.closed")) return;
+		const coordinatorState = (await ctx.session.state(coordinator)).state;
+		if (coordinatorState.closed || coordinatorState.response?.activeRequestId !== requestId) return;
 		if (history.some((event) => {
 			if (event.type === "ai.generation.completed") return event.payload.requestId === requestId;
 			if (event.type !== "ai.generation.failed") return false;
@@ -278,12 +774,23 @@ function createHandlers(options) {
 			return payload.requestId === requestId && payload.superseded !== true;
 		})) return;
 		const previousStarts = history.filter((event) => event.type === "ai.generation.started" && event.payload.requestId === requestId);
-		const attempt = previousStarts.length + 1;
+		if (previousStarts.map((event) => event.payload.attempt).some((priorAttempt) => priorAttempt >= ctx.attempt)) return;
+		const attempt = ctx.attempt;
 		const generationId = `${requestId}:generation:${attempt}`;
 		const responseMessageId = request.responseMessageId ?? (request.reason === "message" ? `${request.messageId}:assistant` : request.messageId);
-		const previous = previousStarts.at(-1);
+		const responseStepCount = history.filter((event) => event.type === "ai.generation.completed" && event.payload.responseMessageId === responseMessageId).length;
+		const sourceCoordinatorState = coordinatorStateAt(history, ctx.event.index);
+		if (request.reason === "tool") {
+			if (!requestId.startsWith("ai.generate:tools:")) return;
+			const sourceGenerationId = requestId.slice(18);
+			if (!continuationReady(sourceCoordinatorState) || sourceCoordinatorState.response?.generation?.generationId !== sourceGenerationId || sourceCoordinatorState.response.responseMessageId !== request.messageId || sourceCoordinatorState.response.responseMessageId !== request.responseMessageId) return;
+		}
+		const previous = previousStarts.filter((event) => event.payload.attempt < attempt).toSorted((left, right) => right.payload.attempt - left.payload.attempt)[0];
 		const incompleteId = previous ? previous.payload.generationId : void 0;
-		const promptHistory = incompleteId === void 0 && request.reason !== "retry" ? history : history.filter((event) => !(event.type === "ai.generation.progress" && (incompleteId !== void 0 && event.payload.generationId === incompleteId || request.reason === "retry" && event.payload.responseMessageId === responseMessageId)));
+		const replacedGenerationIds = /* @__PURE__ */ new Set();
+		if (incompleteId !== void 0) replacedGenerationIds.add(incompleteId);
+		if (request.reason === "retry" && sourceCoordinatorState.response?.failure?.generationId !== void 0) replacedGenerationIds.add(sourceCoordinatorState.response.failure.generationId);
+		const promptHistory = withoutGenerationLifecycle(history, replacedGenerationIds);
 		let state = replay(options.agent, promptHistory);
 		const resolverContext = {
 			event: ctx.event,
@@ -293,6 +800,23 @@ function createHandlers(options) {
 		};
 		const resolvedModel = await resolve(options.model, resolverContext);
 		if (resolvedModel === void 0) throw new TypeError("the model resolver returned undefined");
+		if (ctx.signal.aborted) return;
+		if (request.reason === "tool" && responseStepCount >= maxSteps) {
+			const source = sourceCoordinatorState.response?.generation;
+			if (source === void 0) return;
+			return {
+				type: "ai.generation.failed",
+				id: `${requestId}:step-limit`,
+				payload: {
+					requestId: source.requestId,
+					messageId: source.messageId,
+					generationId: source.generationId,
+					responseMessageId,
+					error: `agent exceeded the ${maxSteps}-step limit`,
+					stepLimit: true
+				}
+			};
+		}
 		const started = {
 			requestId,
 			messageId: request.messageId,
@@ -323,8 +847,14 @@ function createHandlers(options) {
 			id: generationId,
 			payload: started
 		});
-		await ctx.append(...startEvents);
-		let messages = contextMessages(state);
+		await ctx.session.append("generation-start", ...startEvents);
+		const startedCoordinatorState = (await ctx.session.state(coordinator)).state;
+		if (startedCoordinatorState.response?.activeRequestId !== requestId || startedCoordinatorState.response.generation?.generationId !== generationId) return;
+		const promptCoordinatorState = {
+			...coordinatorStateAt(history),
+			queued: queuedMessagesAt(history)
+		};
+		let messages = activeContextMessages(state, promptCoordinatorState);
 		if (options.compaction) {
 			const compactionContext = {
 				...resolverContext,
@@ -332,7 +862,7 @@ function createHandlers(options) {
 			};
 			if (await options.compaction.shouldCompact(compactionContext)) {
 				const throughMessageId = messages.at(-1)?.id ?? request.messageId;
-				await ctx.append({
+				await ctx.session.append("compaction-requested", {
 					type: "ai.compaction.requested",
 					id: `${generationId}:compaction:requested`,
 					payload: {
@@ -344,9 +874,10 @@ function createHandlers(options) {
 				const completed = {
 					generationId,
 					throughMessageId,
-					messages
+					messages,
+					...promptCoordinatorState.queued.length === 0 ? {} : { retainedMessageIds: promptCoordinatorState.queued.map((item) => item.messageId) }
 				};
-				await ctx.append({
+				await ctx.session.append("compaction-completed", {
 					type: "ai.compaction.completed",
 					id: `${generationId}:compaction:completed`,
 					payload: completed
@@ -360,6 +891,11 @@ function createHandlers(options) {
 				};
 			}
 		}
+		const currentState = (await ctx.session.state(options.agent.reducer)).state;
+		const currentCoordinatorState = (await ctx.session.state(coordinator)).state;
+		const generationMessages = activeContextMessages(currentState, currentCoordinatorState);
+		promptCache.set(promptCacheKey(ctx.event.sessionId, generationId), convertToModelMessages(generationMessages, { tools }));
+		let pendingToolCalls = [];
 		try {
 			const resolvedInstructions = options.instructions === void 0 ? void 0 : await resolve(options.instructions, resolverContext);
 			const generateContext = {
@@ -367,15 +903,16 @@ function createHandlers(options) {
 				requestId,
 				generationId,
 				responseMessageId,
-				messages,
-				state,
+				messages: generationMessages,
+				state: currentState,
 				history,
 				signal: ctx.signal,
 				model: resolvedModel,
-				tools: options.tools ?? {},
+				tools,
 				...resolvedInstructions === void 0 ? {} : { instructions: resolvedInstructions },
 				generation: options.generation ?? {}
 			};
+			const custom = options.generate !== void 0;
 			const updates = consumeGeneration({
 				source: options.generate === void 0 ? await generateWithAISDK(generateContext) : { stream: await options.generate(generateContext) },
 				...options.progress === void 0 ? {} : { progress: options.progress }
@@ -396,18 +933,23 @@ function createHandlers(options) {
 					sequence,
 					chunks: update.chunks
 				};
-				const extras = lifecycleEvents({
+				const lifecycle = lifecycleEvents({
 					requestId,
 					messageId: responseMessageId,
 					generationId,
 					sequence,
-					chunks: update.chunks
+					chunks: update.chunks,
+					pending: pendingToolCalls,
+					tools,
+					generation,
+					custom
 				});
-				await ctx.append({
+				pendingToolCalls = lifecycle.pending;
+				await ctx.session.append(`generation-progress:${sequence}`, {
 					type: "ai.generation.progress",
 					id: `${generationId}:progress:${sequence}`,
 					payload: progress
-				}, ...extras);
+				}, ...lifecycle.events);
 				sequence += 1;
 			}
 			if (!finish) throw new Error("agent generation finished without output");
@@ -419,29 +961,37 @@ function createHandlers(options) {
 				...finish.finishReason === void 0 ? {} : { finishReason: finish.finishReason },
 				...finish.usage === void 0 ? {} : { usage: finish.usage }
 			};
-			const messageCompleted = { messageId: responseMessageId };
-			await ctx.append({
+			const completionEvent = {
 				type: "ai.generation.completed",
 				id: `${generationId}:completed`,
 				payload: completed
-			}, {
-				type: "ai.message.completed",
-				id: `${generationId}:message:completed`,
-				payload: messageCompleted
-			});
+			};
+			const unresolved = options.generate ? pendingToolCalls.filter((pending) => pending.classification !== "automatic") : [];
+			if (unresolved.length > 0) throw new Error(`generation ended with unresolved tool authorization for '${unresolved[0].call.toolName}'`);
+			const pendingEvents = pendingToolCalls.filter((pending) => pending.classification === "automatic" || options.generate === void 0 && pending.classification === "unknown").map((pending) => toolCalledEvent(pending.call));
+			if (finish.finishReason === "tool-calls") return [...pendingEvents, completionEvent];
+			return [
+				...pendingEvents,
+				completionEvent,
+				{
+					type: "ai.message.completed",
+					id: `${generationId}:message:completed`,
+					payload: { messageId: responseMessageId }
+				}
+			];
 		} catch (error) {
+			if (error instanceof A2Error) throw error;
 			if (ctx.signal.aborted) {
 				const interrupted = {
 					messageId: responseMessageId,
 					generationId,
 					reason: "aborted"
 				};
-				await ctx.append({
+				return {
 					type: "ai.message.interrupted",
 					id: `${generationId}:interrupted`,
 					payload: interrupted
-				});
-				return;
+				};
 			}
 			const failed = {
 				requestId,
@@ -450,33 +1000,116 @@ function createHandlers(options) {
 				responseMessageId,
 				error: errorMessage(error)
 			};
-			await ctx.append({
+			return {
 				type: "ai.generation.failed",
 				id: `${generationId}:failed`,
 				payload: failed
-			});
+			};
 		}
 	};
-	return { "ai.generation.requested": {
-		abortOn: {
-			"ai.message.interrupted": (event, trigger) => {
-				const responseMessageId = trigger.payload.responseMessageId ?? (trigger.payload.reason === "message" ? `${trigger.payload.messageId}:assistant` : trigger.payload.messageId);
-				return event.payload.messageId === responseMessageId;
+	const handleMessageCreated = async (ctx) => {
+		if (ctx.event.payload.message.role !== "user") return;
+		return scheduleNext(ctx);
+	};
+	const handleRetry = async (ctx) => {
+		const response = (await ctx.session.state(coordinator)).state.response;
+		if (response?.status !== "failed" || response.rootMessageId !== ctx.event.payload.messageId || response.responseMessageId !== ctx.event.payload.responseMessageId) return;
+		return {
+			type: "ai.generation.requested",
+			id: `ai.generate:retry:${ctx.event.payload.retryId}`,
+			payload: {
+				messageId: response.rootMessageId,
+				responseMessageId: response.responseMessageId,
+				reason: "retry"
+			}
+		};
+	};
+	const handleInputResponse = async (ctx) => {
+		const response = (await ctx.session.state(coordinator)).state.response;
+		if (response?.responseMessageId !== ctx.event.payload.messageId || response.inputResponse?.index !== ctx.event.index || response.inputResponse.generationId !== ctx.event.payload.generationId || response.inputResponse.inputId !== ctx.event.payload.inputId) return;
+		await continueIfReady(ctx, ctx.event.payload.generationId);
+	};
+	const clearPromptCache = (sessionId) => {
+		const prefix = `${sessionId}\u001f`;
+		for (const key of promptCache.keys()) if (key.startsWith(prefix)) promptCache.delete(key);
+	};
+	const handleResponseEnded = async (ctx) => {
+		clearPromptCache(ctx.event.sessionId);
+		return scheduleNext(ctx);
+	};
+	return {
+		"ai.message.created": {
+			lane: "a2.ai.turn",
+			handler: handleMessageCreated
+		},
+		"ai.retry.requested": {
+			lane: "a2.ai.turn",
+			handler: handleRetry
+		},
+		"ai.input.responded": {
+			lane: "a2.ai.turn",
+			handler: handleInputResponse
+		},
+		"ai.message.completed": {
+			lane: "a2.ai.turn",
+			handler: handleResponseEnded
+		},
+		"ai.message.interrupted": {
+			lane: "a2.ai.turn",
+			handler: handleResponseEnded
+		},
+		"ai.session.closed": { handler: (ctx) => {
+			clearPromptCache(ctx.event.sessionId);
+			return Promise.resolve();
+		} },
+		"ai.generation.failed": { handler: (ctx) => {
+			promptCache.delete(promptCacheKey(ctx.event.sessionId, ctx.event.payload.generationId));
+			return Promise.resolve();
+		} },
+		"ai.generation.requested": {
+			lane: "a2.ai.turn",
+			abortOn: {
+				"ai.message.interrupted": (event, trigger, context) => {
+					const responseMessageId = trigger.payload.responseMessageId ?? (trigger.payload.reason === "message" ? `${trigger.payload.messageId}:assistant` : trigger.payload.messageId);
+					return event.payload.messageId === responseMessageId && (event.payload.generationId === void 0 || event.payload.generationId === `${trigger.id}:generation:${context.attempt}`);
+				},
+				"ai.session.closed": true
 			},
-			"ai.session.closed": true
+			handler: generationHandler
 		},
-		handler: generationHandler
-	} };
+		"ai.generation.completed": { handler: async (ctx) => continueIfReady(ctx, ctx.event.payload.generationId) },
+		"ai.tool.called": {
+			abortOn: {
+				"ai.generation.failed": (event, trigger) => event.payload.generationId === trigger.payload.generationId,
+				"ai.message.interrupted": (event, trigger) => event.payload.messageId === trigger.payload.messageId && (event.payload.generationId === void 0 || event.payload.generationId === trigger.payload.generationId),
+				"ai.session.closed": true
+			},
+			handler: handleToolCall
+		},
+		"ai.approval.responded": {
+			abortOn: {
+				"ai.generation.failed": (event, trigger) => event.payload.responseMessageId === trigger.payload.messageId && event.payload.generationId === trigger.payload.generationId,
+				"ai.message.interrupted": (event, trigger) => event.payload.messageId === trigger.payload.messageId && (event.payload.generationId === void 0 || event.payload.generationId === trigger.payload.generationId),
+				"ai.session.closed": true
+			},
+			handler: handleApproval
+		},
+		"ai.tool.result": { handler: async (ctx) => {
+			if (ctx.event.payload.preliminary === true) return;
+			await continueIfReady(ctx, ctx.event.payload.generationId);
+		} }
+	};
 }
 /** Assemble an A2 server with the built-in agent handlers and app extensions. */
 function createAgentServer(options) {
-	const { agent: definition, model, tools, instructions, generation, generate, compaction, progress, handlers, ...serverOptions } = options;
+	const { agent: definition, model, tools, instructions, generation, maxSteps, generate, compaction, progress, handlers, ...serverOptions } = options;
 	const builtIns = createHandlers({
 		agent: definition,
 		model,
 		...tools === void 0 ? {} : { tools },
 		...instructions === void 0 ? {} : { instructions },
 		...generation === void 0 ? {} : { generation },
+		...maxSteps === void 0 ? {} : { maxSteps },
 		...generate === void 0 ? {} : { generate },
 		...compaction === void 0 ? {} : { compaction },
 		...progress === void 0 ? {} : { progress }
@@ -487,8 +1120,9 @@ function createAgentServer(options) {
 		handlers: {
 			...builtIns,
 			...handlers
-		}
+		},
+		validatePush: validateAgentPush
 	});
 }
 //#endregion
-export { createAgentServer, createHandlers };
+export { createAgentServer, createHandlers, validateAgentPush };