experimental-a2 0.16.1 → 0.17.0

package/dist/ai-server.js

@@ -1,8 +1,8 @@
-import { n as validateSync } from "./validate-XKT4FSNn.js";
-import { t as A2Error } from "./errors-DCk6ch5n.js";
-import { f as consumeSchedulerSendFailure, p as installAmbientToolScopeStorage } from "./internal-Dq2qYxou.js";
-import { i as setServerFetchHooks, t as createServer } from "./server-BD5ckxZb.js";
-import { C as interruptUIMessage, S as progressBatches, _ as projectedMessage, a as events, b as upsertResponse, d as AI_EVENT_ID_PREFIX, f as aiEventId, g as advanceProjection, h as controlCommit, l as aiStateReducer, m as applyControlChanges, p as initialControlState, u as storedAIReducer, v as reduceToolActivity, w as pauseUIMessage, x as flattenProgressBatches, y as upsertMessage } from "./ai-DgOBltJ_.js";
+import { i as A2Error } from "./session-clear-DGI4jTQ5.js";
+import { a as reducer, s as validateSync } from "./reducer-BAXc8JyF.js";
+import { m as installAmbientToolScopeStorage, p as consumeSchedulerSendFailure } from "./internal-CbVvEwad.js";
+import { a as CONSOLE_TELEMETRY, l as boundedCache, o as setServerFetchHooks, t as createServer } from "./server-Rj64fNvX.js";
+import { A as interruptUIMessage, C as reduceToolActivity, D as flattenProgressBatches, E as upsertResponse, M as assertMessageBase, N as restoreMessageBase, O as progressBatches, S as projectedMessage, T as upsertMessage, _ as applyControlChanges, a as events, b as findMessage, d as appSlice, f as isAgentContract, g as initialControlState, h as aiEventId, j as pauseUIMessage, k as progressOwnedBy, m as AI_EVENT_ID_PREFIX, n as agentContract, p as withAIStorage, u as appReducerOf, v as controlCommit, w as retainMessageBase, y as advanceProjection } from "./ai-UrWfKeuv.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import { asSchema, convertToModelMessages, isToolUIPart, stepCountIs, streamText, toUIMessageStream } from "ai";
@@ -118,7 +118,7 @@ const foldCoordinator = (state, event) => {
 			}));
 			const inputTokens = completion.usage?.inputTokens;
 			const estimate = completion.inputTokenEstimate;
-			return inputTokens !== void 0 && Number.isFinite(inputTokens) && inputTokens >= 0 && estimate !== void 0 ? {
+			return inputTokens !== void 0 && Number.isFinite(inputTokens) && inputTokens >= 0 && estimate !== void 0 && state.response.generation.model !== void 0 ? {
 				...uncalibrated,
 				calibration: {
 					model: state.response.generation.model,
@@ -218,7 +218,8 @@ const foldCoordinator = (state, event) => {
 		default: return state;
 	}
 };
-const aiCoordinatorReducer = (contract) => contract.reducer({
+const aiCoordinatorReducer = (contract) => reducer({
+	contract,
 	name: "a2.ai.coordinator.v6",
 	initialState: {
 		closed: false,
@@ -238,7 +239,9 @@ var ControlCancelled = class extends Error {};
 const callReadyForModel = (call) => call.terminal || call.call.providerExecuted === true && !call.call.supportsDeferredResults && call.response !== void 0;
 const approvalBlocksExecution = (call) => call.approval !== void 0 && call.response?.approved !== true;
 const createControlRuntime = (options) => {
-	const reducer = options.agent.contract.reducer({
+	const telemetry = options.telemetry ?? CONSOLE_TELEMETRY;
+	const reducer$2 = reducer({
+		contract: options.contract,
 		name: "a2.ai.control.v5",
 		initialState: initialControlState()
 	}).fold((state, event) => {
@@ -268,9 +271,9 @@ const createControlRuntime = (options) => {
 			changes: event.payload.changes
 		}) : state;
 	});
-	const coordinator = aiCoordinatorReducer(options.agent.contract);
+	const coordinator = aiCoordinatorReducer(options.contract);
 	const handler = async (ctx) => {
-		const snapshot = await ctx.session.state(reducer, { through: "latest" });
+		const snapshot = await ctx.session.state(reducer$2, { through: "latest" });
 		const before = structuredClone(snapshot.state);
 		const moves = [];
 		const state = structuredClone(snapshot.state);
@@ -502,7 +505,7 @@ const createControlRuntime = (options) => {
 								responseMessageId: response.responseMessageId,
 								reason: "retry"
 							},
-							id: await aiEventId("a2.ai.request.retry", options.agent.contract.name, ctx.event.sessionId, command.request.retryId)
+							id: await aiEventId("a2.ai.request.retry", options.contract.name, ctx.event.sessionId, command.request.retryId)
 						});
 					} else reason = "stale-turn";
 					break;
@@ -634,7 +637,7 @@ const createControlRuntime = (options) => {
 					message: item.message,
 					generate: item.generate
 				},
-				id: await aiEventId("a2.ai.admitted", options.agent.contract.name, ctx.event.sessionId, item.id)
+				id: await aiEventId("a2.ai.admitted", options.contract.name, ctx.event.sessionId, item.id)
 			});
 			if (!item.generate) continue;
 			state.active = {
@@ -645,7 +648,7 @@ const createControlRuntime = (options) => {
 				suspended: false,
 				model: null
 			};
-			const requestId = await aiEventId("a2.ai.request.message", options.agent.contract.name, ctx.event.sessionId, item.id);
+			const requestId = await aiEventId("a2.ai.request.message", options.contract.name, ctx.event.sessionId, item.id);
 			requestModel({
 				request: {
 					messageId: item.id,
@@ -685,7 +688,7 @@ const createControlRuntime = (options) => {
 		const payload = ctx.event.payload;
 		const { turnId, version } = "turnId" in payload ? payload : payload.control;
 		for (const event of events) {
-			const schema = options.agent.contract.events[event.type];
+			const schema = options.contract.events[event.type];
 			const result = validateSync(schema, event.payload, `AI worker ${event.type}`);
 			if (result.issues) throw new TypeError(result.issues.map((issue) => issue.message).join("; "));
 		}
@@ -719,32 +722,39 @@ const createControlRuntime = (options) => {
 		});
 		const persisted = await ctx.session.append(name, ...progress, input);
 		const index = persisted.at(-1).index;
-		const stream = ctx.session.stream({ startAfter: index })[Symbol.asyncIterator]();
-		const canonical = [];
-		const wanted = new Set(lifecycle.map((event) => event.id));
-		let rejectAbort;
-		const aborted = new Promise((_, reject) => {
-			rejectAbort = reject;
-		});
-		const onAbort = () => {
-			rejectAbort(ctx.signal.reason);
-		};
-		ctx.signal.addEventListener("abort", onAbort, { once: true });
-		try {
-			ctx.signal.throwIfAborted();
-			for (;;) {
-				const item = await Promise.race([stream.next(), aborted]);
-				if (item.done) throw new Error("AI control acknowledgement stream ended");
-				if (wanted.has(item.value.id)) canonical.push(item.value);
-				if (item.value.type === "ai.control.decided" && item.value.payload.commandId === input.id) {
-					if (item.value.payload.outcome === "rejected") throw new ControlCancelled("stale AI work");
-					return [...persisted.filter((event) => event.type !== "ai.work.reported"), ...canonical];
+		return telemetry.span("a2.ai.ack", {
+			"a2.contract": options.contract.name,
+			"a2.session_id": ctx.event.sessionId,
+			"a2.ai.ack.request_id": ctx.event.id,
+			"a2.ai.ack.report_id": input.id
+		}, async () => {
+			const stream = ctx.session.stream({ startAfter: index })[Symbol.asyncIterator]();
+			const canonical = [];
+			const wanted = new Set(lifecycle.map((event) => event.id));
+			let rejectAbort;
+			const aborted = new Promise((_, reject) => {
+				rejectAbort = reject;
+			});
+			const onAbort = () => {
+				rejectAbort(ctx.signal.reason);
+			};
+			ctx.signal.addEventListener("abort", onAbort, { once: true });
+			try {
+				ctx.signal.throwIfAborted();
+				for (;;) {
+					const item = await Promise.race([stream.next(), aborted]);
+					if (item.done) throw new Error("AI control acknowledgement stream ended");
+					if (wanted.has(item.value.id)) canonical.push(item.value);
+					if (item.value.type === "ai.control.decided" && item.value.payload.commandId === input.id) {
+						if (item.value.payload.outcome === "rejected") throw new ControlCancelled("stale AI work");
+						return [...persisted.filter((event) => event.type !== "ai.work.reported"), ...canonical];
+					}
 				}
+			} finally {
+				ctx.signal.removeEventListener("abort", onAbort);
+				await stream.return?.();
 			}
-		} finally {
-			ctx.signal.removeEventListener("abort", onAbort);
-			await stream.return?.();
-		}
+		});
 	};
 	const settled = ({ ctx, events }) => report({
 		ctx,
@@ -761,7 +771,7 @@ const createControlRuntime = (options) => {
 		append,
 		settled,
 		cancelled,
-		reducer,
+		reducer: reducer$2,
 		coordinator
 	};
 };
@@ -802,19 +812,29 @@ const progress = (value) => {
 	return count === value["length"];
 };
 const indexedEvents = (value, types) => Array.isArray(value) && value.every((event) => record(event) && index(event["index"]) && types.includes(event["type"]) && matches(events[event["type"]], event["payload"]));
+const restorableBase = (options) => {
+	assertMessageBase(options.base);
+	return isMessage(restoreMessageBase({
+		current: options.current,
+		base: options.base
+	}));
+};
 const projection = (value, messages) => {
 	if (!record(value) || Object.keys(value).some((key) => ![
 		"generationId",
 		"responseMessageId",
 		"promptThroughIndex",
 		"completionIndex",
-		"baseMessage",
+		"base",
 		"baseCompaction",
 		"batches",
 		"toolEvents",
 		"approvalEvents",
 		"cursor"
-	].includes(key)) || !id(value["generationId"]) || !id(value["responseMessageId"]) || !index(value["promptThroughIndex"]) || value["completionIndex"] !== void 0 && !index(value["completionIndex"]) || value["baseMessage"] !== void 0 && !isMessage(value["baseMessage"]) || value["baseCompaction"] !== void 0 && !compaction(value["baseCompaction"]) || !progress(value["batches"]) || !indexedEvents(value["toolEvents"], ["ai.tool.called", "ai.tool.result"]) || !indexedEvents(value["approvalEvents"], ["ai.approval.requested", "ai.approval.responded"])) return false;
+	].includes(key)) || !id(value["generationId"]) || !id(value["responseMessageId"]) || !index(value["promptThroughIndex"]) || value["completionIndex"] !== void 0 && !index(value["completionIndex"]) || value["base"] !== void 0 && !restorableBase({
+		base: value["base"],
+		current: messages.find((message) => message.id === value["responseMessageId"])
+	}) || value["baseCompaction"] !== void 0 && !compaction(value["baseCompaction"]) || !progress(value["batches"]) || !indexedEvents(value["toolEvents"], ["ai.tool.called", "ai.tool.result"]) || !indexedEvents(value["approvalEvents"], ["ai.approval.requested", "ai.approval.responded"])) return false;
 	const cursor = value["cursor"];
 	if (cursor === void 0 || cursor === null) return true;
 	if (!record(cursor) || !index(cursor["throughIndex"]) || !record(cursor["stream"])) return false;
@@ -848,7 +868,7 @@ const authority = (value) => value === null || record(value) && Object.keys(valu
 	"pausing",
 	"paused"
 ].includes(String(value["phase"])));
-const contextSchema = () => ({ "~standard": {
+const contextSchema = (app) => ({ "~standard": {
 	version: 1,
 	vendor: "a2-context",
 	validate(value) {
@@ -861,7 +881,8 @@ const contextSchema = () => ({ "~standard": {
 			"authority",
 			"generation",
 			"activeProjection",
-			"messageIndexes"
+			"messageIndexes",
+			...app === void 0 ? [] : ["app"]
 		];
 		try {
 			if (!record(value) || keys.some((key) => !Object.hasOwn(value, key)) || Object.keys(value).some((key) => !keys.includes(key))) return invalid;
@@ -873,7 +894,7 @@ const contextSchema = () => ({ "~standard": {
 				modelId,
 				limits: entry["limits"]
 			}))) || !indexes(value["messageIndexes"], messages)) return invalid;
-			if (generation !== null && (!record(generation) || !matches(events["ai.generation.started"], generation["owner"]) || ![
+			if (generation !== null && (!record(generation) || !matches(events["ai.generation.started"], generation["owner"]) || !index(generation["startIndex"]) || ![
 				"streaming",
 				"completed",
 				"paused",
@@ -884,6 +905,7 @@ const contextSchema = () => ({ "~standard": {
 			if (current !== null && (!projection(current, messages) || !record(current) || current["generationId"] !== owner?.["generationId"] || current["responseMessageId"] !== owner?.["responseMessageId"])) return invalid;
 			if (generation !== null && generation["phase"] !== "superseded" && current === null) return invalid;
 			if (value["closed"] && (generation !== null || current !== null)) return invalid;
+			if (app !== void 0 && !record(value["app"])) return invalid;
 			return { value };
 		} catch {
 			return invalid;
@@ -911,14 +933,24 @@ const replaceResponse = ({ state, message, index }) => {
 		}
 	};
 };
-const calledTools = (projection) => /* @__PURE__ */ new Set([...projection.baseMessage?.parts.flatMap((part) => "toolCallId" in part ? [part.toolCallId] : []) ?? [], ...projection.toolEvents.filter((event) => event.type === "ai.tool.called").map((event) => event.payload.toolCallId)]);
+const calledTools = ({ projection, current }) => /* @__PURE__ */ new Set([...restoreMessageBase({
+	current,
+	base: projection.base
+})?.parts.flatMap((part) => "toolCallId" in part ? [part.toolCallId] : []) ?? [], ...projection.toolEvents.filter((event) => event.type === "ai.tool.called").map((event) => event.payload.toolCallId)]);
 const renderProjection = ({ state, index }) => {
 	const projection = state.activeProjection;
-	let message = projectedMessage(projection);
-	if (projection.baseMessage === void 0 && projection.batches.length === 0 && message.parts.length === 0) return state;
+	const current = findMessage(state.messages, projection.responseMessageId);
+	let message = projectedMessage({
+		projection,
+		current
+	});
+	if (projection.base === void 0 && projection.batches.length === 0 && message.parts.length === 0) return state;
 	if (state.generation?.phase === "paused") message = pauseUIMessage({
 		message,
-		toolCallIds: calledTools(projection)
+		toolCallIds: calledTools({
+			projection,
+			current
+		})
 	});
 	if (state.generation?.phase === "failed") message = interruptUIMessage(message, `Generation failed before tool completion: ${state.generation.error}`);
 	return replaceResponse({
@@ -936,9 +968,13 @@ const renderProjection = ({ state, index }) => {
 const generationBase = (state) => {
 	const projection = state.activeProjection;
 	if (!projection) return state;
+	const base = restoreMessageBase({
+		current: findMessage(state.messages, projection.responseMessageId),
+		base: projection.base
+	});
 	return {
 		...state,
-		messages: projection.baseMessage === void 0 ? state.messages.filter((message) => message.id !== projection.responseMessageId) : upsertMessage(state.messages, projection.baseMessage),
+		messages: base === void 0 ? state.messages.filter((message) => message.id !== projection.responseMessageId) : upsertMessage(state.messages, base),
 		compaction: projection.baseCompaction ?? null
 	};
 };
@@ -957,22 +993,37 @@ const endGeneration = (state) => ({
 	activeProjection: null
 });
 const ownsGeneration = (state, owner) => state.generation?.owner.generationId === owner.generationId && state.generation.owner.requestId === owner.requestId && state.generation.phase !== "superseded";
-const createContextReducer = ({ agent }) => {
-	const reducer = agent.contract.reducer({
-		name: "a2.ai.context.v3",
-		initialState: {
-			messages: [],
-			compaction: null,
-			modelMetadata: {},
-			closed: false,
-			authority: null,
-			generation: null,
-			activeProjection: null,
-			messageIndexes: {}
-		},
-		stateSchema: contextSchema()
-	}).fold((state, event) => reduceContext(state, event));
-	return storedAIReducer(reducer);
+const createContextReducer = ({ contract }) => {
+	const app = appReducerOf(contract);
+	const initialState = {
+		messages: [],
+		compaction: null,
+		modelMetadata: {},
+		closed: false,
+		authority: null,
+		generation: null,
+		activeProjection: null,
+		messageIndexes: {},
+		...app === void 0 ? {} : { app: app.initialState }
+	};
+	const reducer$1 = reducer({
+		contract,
+		name: app === void 0 ? "a2.ai.context.v6" : `${app.name}+a2.ai.context.v6`,
+		initialState,
+		stateSchema: contextSchema(app)
+	}).fold((state, event) => {
+		const after = retainMessageBase({
+			before: state,
+			after: reduceContext(state, event)
+		});
+		if (app === void 0) return after;
+		const next = app.fold(state.app, event);
+		return next === state.app ? after : {
+			...after,
+			app: appSlice(next)
+		};
+	});
+	return withAIStorage(reducer$1);
 };
 const reduceContext = (state, event) => {
 	if (state.closed) return state;
@@ -1029,6 +1080,7 @@ const reduceContext = (state, event) => {
 				...base,
 				generation: {
 					owner,
+					startIndex: event.index,
 					phase: "streaming",
 					...previous?.owner.responseMessageId === owner.responseMessageId && previous.responseIndex !== void 0 ? { responseIndex: previous.responseIndex } : {}
 				},
@@ -1036,7 +1088,7 @@ const reduceContext = (state, event) => {
 					generationId: owner.generationId,
 					responseMessageId: owner.responseMessageId,
 					promptThroughIndex: owner.promptThroughIndex ?? event.index - 1,
-					...baseMessage === void 0 ? {} : { baseMessage },
+					...baseMessage === void 0 ? {} : { base: { partCount: baseMessage.parts.length } },
 					baseCompaction: base.compaction,
 					batches: progressBatches(),
 					toolEvents: [],
@@ -1046,7 +1098,12 @@ const reduceContext = (state, event) => {
 		}
 		case "ai.generation.progress": {
 			const payload = event.payload;
-			if (!ownsGeneration(state, payload) || state.generation.owner.responseMessageId !== payload.responseMessageId || state.generation.phase !== "streaming" || !state.activeProjection) return state;
+			const generation = state.generation;
+			if (generation === null || generation.phase !== "streaming" || !progressOwnedBy({
+				payload,
+				owner: generation.owner,
+				startIndex: generation.startIndex
+			}) || !state.activeProjection) return state;
 			const projection = state.activeProjection;
 			const progress = advanceProjection({
 				projection,
@@ -1125,9 +1182,12 @@ const reduceContext = (state, event) => {
 				approvalEvents: projection.approvalEvents.filter((item) => item.index <= cutoff)
 			};
 			let next = generationBase(state);
-			if (retained.baseMessage !== void 0 || retained.batches.length > 0) next = replaceResponse({
+			if (retained.base !== void 0 || retained.batches.length > 0) next = replaceResponse({
 				state: next,
-				message: interruptUIMessage(projectedMessage(retained)),
+				message: interruptUIMessage(projectedMessage({
+					projection: retained,
+					current: findMessage(state.messages, retained.responseMessageId)
+				})),
 				index: event.index
 			});
 			return endGeneration(next);
@@ -1139,7 +1199,10 @@ const reduceContext = (state, event) => {
 		case "ai.generation.paused": {
 			const { generationId } = event.payload;
 			if (state.generation?.owner.generationId !== generationId || state.generation.phase === "failed" || state.generation.phase === "superseded" || !state.activeProjection) return state;
-			const toolCallIds = calledTools(state.activeProjection);
+			const toolCallIds = calledTools({
+				projection: state.activeProjection,
+				current: findMessage(state.messages, state.activeProjection.responseMessageId)
+			});
 			return renderProjection({
 				state: {
 					...state,
@@ -1242,9 +1305,9 @@ const reduceContext = (state, event) => {
 				...projection,
 				cursor: null
 			};
-			delete activeProjection.baseMessage;
+			delete activeProjection.base;
 			const baseMessage = messages.find((message) => message.id === projection.responseMessageId);
-			if (baseMessage !== void 0) activeProjection.baseMessage = baseMessage;
+			if (baseMessage !== void 0) activeProjection.base = { partCount: baseMessage.parts.length };
 			const compaction = {
 				status: "completed",
 				generationId: payload.generationId,
@@ -1467,23 +1530,24 @@ const measuredInputTokens = (options) => {
 	return previous !== void 0 && previous.model === options.model && options.estimate >= previous.estimate ? Math.ceil(previous.inputTokens + options.estimate - previous.estimate) : options.estimate;
 };
 //#endregion
-//#region src/ai-server.ts
+//#region src/ai-agent.ts
 /**
-* 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.
+* The server-only implementation of the experimental-a2/ai protocol: the
+* handler table and `agent()`, its assembly as an ordinary A2 server.
 */
-function validateAgentIngress(context) {
-	const rejected = context.events.find((event) => {
-		if (event.type !== "ai.control.requested") return true;
-		const command = event.payload;
-		if (command["action"] === "request-input" || command["action"] === "tool-result") return true;
-		if (command["action"] === "send" || command["action"] === "edit" || command["action"] === "steer") return command["message"]?.role !== "user";
-		return false;
-	});
+const isAgentIngressEvent = (event) => {
+	if (event.type !== "ai.control.requested") return false;
+	const command = event.payload;
+	if (typeof command !== "object" || command === null) return false;
+	const action = command.action;
+	if (action === "request-input" || action === "tool-result") return false;
+	if (action === "send" || action === "edit" || action === "steer") return command.message?.role === "user";
+	return true;
+};
+const validateAgentIngress = ({ context, applicationEvents }) => {
+	const rejected = context.events.find((event) => Object.hasOwn(events, event.type) ? !isAgentIngressEvent(event) : !applicationEvents);
 	if (rejected !== void 0) throw new A2Error("INVALID_PAYLOAD", `event '${rejected.type}' is server-only for an AI agent`);
-}
+};
 const checkAbort = (signal) => {
 	if (!signal.aborted) return false;
 	const reason = signal.reason;
@@ -1501,6 +1565,22 @@ const resolve = async (value, context) => {
 	checkAbort(context.signal);
 	return result;
 };
+const withModelSettings = (options) => {
+	const { generation, settings } = options;
+	if (settings.reasoning === void 0 && settings.speed === void 0) return generation;
+	const { speed: _speed, ...gateway } = generation.providerOptions?.["gateway"] ?? {};
+	return {
+		...generation,
+		...settings.reasoning === void 0 ? {} : { reasoning: settings.reasoning },
+		...settings.speed === void 0 ? {} : { providerOptions: {
+			...generation.providerOptions,
+			gateway: settings.speed === "fast" ? {
+				...gateway,
+				speed: "fast"
+			} : gateway
+		} }
+	};
+};
 const modelName = (model) => {
 	if (typeof model === "string") return model;
 	if ("modelId" in model && typeof model.modelId === "string") return model.modelId;
@@ -1512,7 +1592,8 @@ const toolScopeStorage = installAmbientToolScopeStorage(() => new AsyncLocalStor
 function runWithHandlerContext(ctx, fn) {
 	return toolScopeStorage.run({ context: ctx }, fn);
 }
-const promptCacheKey = (sessionId, generationId) => `${sessionId}\u001f${generationId}`;
+/** Sessions whose latest step prompt one process keeps for that step's tools. */
+const PROMPT_SESSIONS = 64;
 const asyncIterator = (value) => {
 	if (typeof value !== "object" || value === null) return void 0;
 	const factory = Reflect.get(value, Symbol.asyncIterator);
@@ -1520,6 +1601,49 @@ const asyncIterator = (value) => {
 	return factory.call(value);
 };
 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 DELTA_KEYS = {
+	"text-delta": /* @__PURE__ */ new Set([
+		"type",
+		"id",
+		"delta",
+		"providerMetadata"
+	]),
+	"reasoning-delta": /* @__PURE__ */ new Set([
+		"type",
+		"id",
+		"delta",
+		"providerMetadata"
+	]),
+	"tool-input-delta": /* @__PURE__ */ new Set([
+		"type",
+		"toolCallId",
+		"inputTextDelta"
+	])
+};
+const isDeltaChunk = (chunk) => Object.hasOwn(DELTA_KEYS, chunk.type) && Object.keys(chunk).every((key) => DELTA_KEYS[chunk.type].has(key)) && typeof (chunk.type === "tool-input-delta" ? chunk.inputTextDelta : chunk.delta) === "string";
+const joinDeltas = (left, right) => {
+	if (left.type === "tool-input-delta") return right.type === "tool-input-delta" && right.toolCallId === left.toolCallId ? {
+		...left,
+		inputTextDelta: left.inputTextDelta + right.inputTextDelta
+	} : void 0;
+	if (right.type === "tool-input-delta" || right.type !== left.type || right.id !== left.id) return void 0;
+	const providerMetadata = right.providerMetadata !== void 0 ? right.providerMetadata : left.providerMetadata;
+	return {
+		...left,
+		delta: left.delta + right.delta,
+		...providerMetadata === void 0 ? {} : { providerMetadata }
+	};
+};
+const mergeDeltas = (chunks) => {
+	const merged = [];
+	for (const chunk of chunks) {
+		const previous = merged.at(-1);
+		const joined = previous !== void 0 && isDeltaChunk(previous) && isDeltaChunk(chunk) ? joinDeltas(previous, chunk) : void 0;
+		if (joined === void 0) merged.push(chunk);
+		else merged[merged.length - 1] = joined;
+	}
+	return merged;
+};
 const nextOrTimer = async (next, delayMs) => {
 	let timer;
 	try {
@@ -1541,7 +1665,7 @@ async function generateWithAISDK(options) {
 		...context.generation,
 		headers: Object.keys(headers).some((key) => key.toLowerCase() === "x-session-affinity") ? headers : {
 			...headers,
-			"x-session-affinity": createHash("sha256").update(JSON.stringify([agentName, context.request.sessionId])).digest("hex")
+			"x-session-affinity": createHash("sha256").update(JSON.stringify([agentName, context.event.sessionId])).digest("hex")
 		},
 		providerOptions: {
 			...context.generation.providerOptions,
@@ -1556,7 +1680,7 @@ async function generateWithAISDK(options) {
 		tools: context.tools,
 		messages: context.messages,
 		modelMessages: context.modelMessages,
-		responseMessageId: context.responseMessageId,
+		responseMessageId: context.event.payload.responseMessageId,
 		abortSignal: context.signal,
 		...context.instructions === void 0 ? {} : { instructions: context.instructions },
 		settings: generation,
@@ -1575,9 +1699,13 @@ async function* consumeGeneration(options) {
 	const pending = [];
 	let streamedFinishReason;
 	let streamedError;
-	const maxChunks = options.progress?.maxChunks ?? 16;
-	const maxDelayMs = options.progress?.maxDelayMs ?? 30;
+	const maxChunks = options.progress?.maxChunks ?? 128;
+	const maxDelayMs = options.progress?.maxDelayMs ?? 0;
 	let lastFlush = Date.now();
+	const batch = () => ({
+		type: "progress",
+		chunks: mergeDeltas(pending.splice(0))
+	});
 	const reader = options.source.stream.getReader();
 	let pendingChunk = reader.read();
 	try {
@@ -1587,10 +1715,7 @@ async function* consumeGeneration(options) {
 				const remaining = Math.max(0, maxDelayMs - (Date.now() - lastFlush));
 				const outcome = await nextOrTimer(pendingChunk, remaining);
 				if (outcome.type === "timer") {
-					yield {
-						type: "progress",
-						chunks: pending.splice(0)
-					};
+					yield batch();
 					lastFlush = Date.now();
 					continue;
 				}
@@ -1603,18 +1728,12 @@ async function* consumeGeneration(options) {
 			if (chunk.type === "error") streamedError = chunk.errorText;
 			pendingChunk = reader.read();
 			if (pending.length >= maxChunks || isBoundaryChunk(pending.at(-1))) {
-				yield {
-					type: "progress",
-					chunks: pending.splice(0)
-				};
+				yield batch();
 				lastFlush = Date.now();
 			}
 		}
 	} catch (error) {
-		if (pending.length > 0) yield {
-			type: "progress",
-			chunks: pending.splice(0)
-		};
+		if (pending.length > 0) yield batch();
 		throw error;
 	} finally {
 		pendingChunk.catch(() => {});
@@ -1628,16 +1747,10 @@ async function* consumeGeneration(options) {
 	try {
 		completion = options.source.completion?.();
 	} catch (error) {
-		if (pending.length > 0) yield {
-			type: "progress",
-			chunks: pending.splice(0)
-		};
+		if (pending.length > 0) yield batch();
 		throw error;
 	}
-	if (pending.length > 0) yield {
-		type: "progress",
-		chunks: pending.splice(0)
-	};
+	if (pending.length > 0) yield batch();
 	if (streamedError !== void 0) throw new Error(streamedError);
 	const finishReason = completion?.finishReason ?? streamedFinishReason;
 	yield {
@@ -1688,8 +1801,7 @@ const summarize = async (options) => {
 			modelMessages: [...options.context.modelMessages, {
 				role: "user",
 				content: instruction
-			}],
-			responseMessageId: await aiEventId("a2.ai.summary", options.context.generationId)
+			}]
 		},
 		messageMetadata: void 0
 	});
@@ -1916,12 +2028,8 @@ const validateCompaction = (options) => {
 	}
 	return compaction;
 };
-/**
-* Build the ordinary A2 handler table for the built-in agent protocol.
-* Application handlers can be spread beside this table.
-*/
 function createHandlers(options) {
-	if (options.model === void 0) throw new TypeError("createHandlers requires model");
+	if (options.model === void 0) throw new TypeError("agent 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 && options.maxSteps !== Number.POSITIVE_INFINITY && (!Number.isInteger(options.maxSteps) || options.maxSteps < 1)) throw new TypeError("maxSteps must be a positive integer or Infinity");
@@ -1929,23 +2037,39 @@ function createHandlers(options) {
 	const staticCompaction = typeof configuredCompaction === "function" ? void 0 : validateCompaction({
 		compaction: configuredCompaction,
 		explicit: options.compaction !== void 0,
-		generation: options.generation,
+		generation: typeof options.generation === "function" ? void 0 : options.generation,
 		tools: options.tools
 	});
 	const tools = options.tools ?? {};
-	const generation = options.generation ?? {};
+	const telemetry = options.telemetry ?? CONSOLE_TELEMETRY;
 	const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY;
-	const control = createControlRuntime({ agent: options.agent });
+	const control = createControlRuntime({
+		contract: options.contract,
+		telemetry
+	});
+	const controlHandler = (ctx) => telemetry.span("a2.ai.control", {
+		"a2.contract": options.contract.name,
+		"a2.session_id": ctx.event.sessionId,
+		"a2.ai.control.type": ctx.event.type,
+		"a2.ai.control.id": ctx.event.id,
+		"a2.ai.control.attempt": ctx.attempt
+	}, () => control.handler(ctx));
 	const coordinator = control.coordinator;
-	const contextReducer = createContextReducer({ agent: options.agent });
+	const contextReducer = createContextReducer({ contract: options.contract });
 	const readContext = async (session, through) => {
-		const snapshot = await session.state(contextReducer, { through });
-		return {
-			state: contextReducer.view(snapshot.state),
-			index: snapshot.index
-		};
+		return await session.state(contextReducer, { through });
+	};
+	const prompts = boundedCache({
+		maxEntries: PROMPT_SESSIONS,
+		maxBytes: PROMPT_SESSIONS
+	});
+	const cachePrompt = ({ sessionId, generationId, messages }) => prompts.set(sessionId, {
+		generationId,
+		messages
+	}, 1);
+	const forgetPrompt = (sessionId, generationId) => {
+		if (prompts.get(sessionId)?.generationId === generationId) prompts.delete(sessionId);
 	};
-	const promptCache = /* @__PURE__ */ new Map();
 	const resultEvent = async (call, suffix, result) => ({
 		type: "ai.tool.result",
 		id: await aiEventId("a2.ai.tool.result", call.generationId, call.toolCallId, suffix),
@@ -1968,25 +2092,32 @@ function createHandlers(options) {
 	});
 	const promptMessages = (input) => {
 		const { ctx, call, generation: owner } = input;
-		const key = promptCacheKey(ctx.event.sessionId, call.generationId);
-		const cached = promptCache.get(key);
-		if (cached) return cached;
+		const sessionId = ctx.event.sessionId;
+		const cached = prompts.get(sessionId);
+		if (cached?.generationId === call.generationId) return cached.messages;
 		const computation = (async () => {
 			const frontier = owner.promptThroughIndex;
 			if (frontier === void 0) throw new TypeError("AI work requires a prompt checkpoint");
 			const snapshot = await readContext(ctx.session, ctx.event.index);
 			if (snapshot.state.generation?.owner.generationId !== owner.generationId || snapshot.state.generation.owner.requestId !== owner.requestId || snapshot.state.activeProjection?.generationId !== owner.generationId) throw new TypeError("Tool prompt checkpoint does not own its generation");
 			const state = generationBase(snapshot.state);
-			return modelContext({
+			return telemetry.span("a2.ai.context", {
+				"a2.contract": options.contract.name,
+				"a2.session_id": ctx.event.sessionId,
+				"a2.ai.context.request_id": call.requestId,
+				"a2.ai.context.phase": "tool"
+			}, () => modelContext({
 				messages: state.messages.filter((message) => state.messageIndexes[message.id] <= frontier),
 				state,
 				tools
-			});
+			}));
 		})();
-		promptCache.set(key, computation);
-		computation.catch(() => {
-			if (promptCache.get(key) === computation) promptCache.delete(key);
+		cachePrompt({
+			sessionId,
+			generationId: call.generationId,
+			messages: computation
 		});
+		computation.catch(() => forgetPrompt(sessionId, call.generationId));
 		return computation;
 	};
 	const toolExecutionFailure = async (ctx, call, error) => {
@@ -2055,7 +2186,7 @@ function createHandlers(options) {
 		const messages = await promptMessages(input);
 		if (checkAbort(ctx.signal)) return;
 		const scope = {
-			contract: options.agent.contract,
+			contract: options.contract,
 			context: ctx
 		};
 		return toolScopeStorage.run(scope, () => runToolExecution(ctx, call, execute, messages));
@@ -2115,109 +2246,124 @@ function createHandlers(options) {
 				state,
 				coordinator: coordinatorState
 			}),
+			state: snapshot.state.app ?? {},
 			session: { state: (reducer, readOptions) => ctx.session.state(reducer, {
 				...readOptions,
 				through: readOptions?.through ?? snapshot.index
 			}) },
 			signal: ctx.signal
 		};
-		let generationStarted = false;
-		try {
-			const resolvedModel = await resolve(options.model, resolverContext);
-			if (resolvedModel === void 0) throw new TypeError("the model resolver returned undefined");
-			if (checkAbort(ctx.signal)) return;
-			const resolvedInstructions = options.instructions === void 0 ? void 0 : await resolve(options.instructions, resolverContext);
-			if (checkAbort(ctx.signal)) return;
-			const compaction = typeof configuredCompaction === "function" ? validateCompaction({
-				compaction: await resolve(configuredCompaction, resolverContext),
-				explicit: true,
-				generation: options.generation,
-				tools: options.tools
-			}) : staticCompaction;
-			if (checkAbort(ctx.signal)) return;
-			if (request.reason === "tool" && responseStepCount >= maxSteps) {
-				const source = response.source?.generation;
-				if (source === void 0) return;
-				return {
-					type: "ai.generation.failed",
-					id: await aiEventId("a2.ai.step-limit", requestId),
-					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,
-				generationId,
-				responseMessageId,
-				attempt,
-				model: modelName(resolvedModel),
-				promptThroughIndex: snapshot.index
+		if (request.reason === "tool" && responseStepCount >= maxSteps) {
+			const source = response.source?.generation;
+			if (source === void 0) return;
+			return {
+				type: "ai.generation.failed",
+				id: await aiEventId("a2.ai.step-limit", requestId),
+				payload: {
+					requestId: source.requestId,
+					messageId: source.messageId,
+					generationId: source.generationId,
+					responseMessageId,
+					error: `agent exceeded the ${maxSteps}-step limit`,
+					stepLimit: true
+				}
 			};
-			const catalogModelId = gatewayModelId(resolvedModel);
-			const gatewayOptions = options.generation?.providerOptions?.["gateway"];
-			const usesFallbackModels = Array.isArray(gatewayOptions?.["models"]) && gatewayOptions["models"].length > 0;
-			const discoversMetadata = compaction !== false && !("shouldCompact" in compaction) && compaction.thresholdTokens === void 0 && !usesFallbackModels && catalogModelId !== void 0;
-			const startEvents = [];
-			if (discoversMetadata && !Object.hasOwn(state.modelMetadata, catalogModelId)) startEvents.push({
+		}
+		const startEvents = async (started, metadataModelId) => {
+			const events = [];
+			if (metadataModelId !== void 0) events.push({
 				type: "ai.model.metadata.requested",
-				id: await aiEventId("a2.ai.model.metadata", options.agent.contract.name, ctx.event.sessionId, catalogModelId),
-				payload: { modelId: catalogModelId }
+				id: await aiEventId("a2.ai.model.metadata", options.contract.name, ctx.event.sessionId, metadataModelId),
+				payload: { modelId: metadataModelId }
 			});
 			if (previous) {
-				const payload = previous;
 				const superseded = {
 					requestId,
-					messageId: payload.messageId,
-					generationId: payload.generationId,
-					responseMessageId: payload.responseMessageId,
+					messageId: previous.messageId,
+					generationId: previous.generationId,
+					responseMessageId: previous.responseMessageId,
 					error: "generation attempt was superseded after an incomplete run",
 					superseded: true
 				};
-				startEvents.push({
+				events.push({
 					type: "ai.generation.failed",
-					id: await aiEventId("a2.ai.superseded", payload.generationId),
+					id: await aiEventId("a2.ai.superseded", previous.generationId),
 					payload: superseded
 				});
 			}
-			startEvents.push({
+			events.push({
 				type: "ai.generation.started",
 				id: generationId,
 				payload: started
 			});
+			return events;
+		};
+		const startedPayload = (model) => ({
+			requestId,
+			messageId: request.messageId,
+			generationId,
+			responseMessageId,
+			attempt,
+			...model === void 0 ? {} : { model: modelName(model) },
+			promptThroughIndex: snapshot.index
+		});
+		let resolvedModel;
+		let resolving = true;
+		let generationStarted = false;
+		try {
+			const choice = await resolve(options.model, resolverContext);
+			if (choice === void 0) throw new TypeError("the model resolver returned undefined");
+			const settings = typeof choice === "string" || "specificationVersion" in choice ? { model: choice } : choice;
+			const model = settings.model;
+			if (typeof model !== "string" && (typeof model !== "object" || model === null)) throw new TypeError("the model resolver must return a model");
+			resolvedModel = model;
+			if (checkAbort(ctx.signal)) return;
+			const resolvedInstructions = options.instructions === void 0 ? void 0 : await resolve(options.instructions, resolverContext);
+			if (checkAbort(ctx.signal)) return;
+			const resolvedGeneration = await resolve(options.generation ?? {}, resolverContext);
+			if (checkAbort(ctx.signal)) return;
+			if (resolvedGeneration === null || typeof resolvedGeneration !== "object" || Array.isArray(resolvedGeneration)) throw new TypeError("the generation resolver must return settings");
+			const generation = withModelSettings({
+				generation: resolvedGeneration,
+				settings
+			});
+			const compaction = typeof configuredCompaction === "function" || typeof options.generation === "function" ? validateCompaction({
+				compaction: typeof configuredCompaction === "function" ? await resolve(configuredCompaction, resolverContext) : staticCompaction,
+				explicit: options.compaction !== void 0,
+				generation,
+				tools: options.tools
+			}) : staticCompaction;
+			if (checkAbort(ctx.signal)) return;
+			resolving = false;
+			const catalogModelId = gatewayModelId(model);
+			const gatewayOptions = generation.providerOptions?.["gateway"];
+			const usesFallbackModels = Array.isArray(gatewayOptions?.["models"]) && gatewayOptions["models"].length > 0;
+			const discoversMetadata = compaction !== false && !("shouldCompact" in compaction) && compaction.thresholdTokens === void 0 && !usesFallbackModels && catalogModelId !== void 0;
 			const generationEvents = await control.append({
 				ctx,
 				name: "generation-start",
-				events: startEvents
+				events: await startEvents(startedPayload(model), discoversMetadata && !Object.hasOwn(state.modelMetadata, catalogModelId) ? catalogModelId : void 0)
 			});
+			const startIndex = generationEvents.find((event) => event.id === generationId).index;
 			generationStarted = true;
 			if (checkAbort(ctx.signal)) return;
 			const promptCoordinatorState = coordinatorState;
-			const messages = contextMessages({
-				state,
-				coordinator: promptCoordinatorState
-			});
+			const { messages } = resolverContext;
 			let generationMessages = messages;
-			let modelMessages = await modelContext({
+			let modelMessages = await telemetry.span("a2.ai.context", {
+				"a2.contract": options.contract.name,
+				"a2.session_id": ctx.event.sessionId,
+				"a2.ai.context.request_id": requestId,
+				"a2.ai.context.phase": "generation"
+			}, () => modelContext({
 				messages,
 				state,
 				tools
-			});
+			}));
 			const baseContext = {
-				request: ctx.event,
-				requestId,
+				...resolverContext,
 				generationId,
-				responseMessageId,
-				messages,
 				modelMessages,
-				session: resolverContext.session,
-				signal: ctx.signal,
 				model: resolvedModel,
 				tools,
 				...resolvedInstructions === void 0 ? {} : { instructions: resolvedInstructions },
@@ -2282,14 +2428,20 @@ function createHandlers(options) {
 							}
 						}]
 					}));
-					const result = !("shouldCompact" in policy) ? {
+					const result = await telemetry.span("a2.ai.compaction", {
+						"a2.contract": options.contract.name,
+						"a2.session_id": ctx.event.sessionId,
+						"a2.ai.compaction.request_id": requestId,
+						"a2.ai.compaction.generation_id": generationId,
+						"a2.ai.compaction.policy": "shouldCompact" in policy ? "custom" : "automatic"
+					}, async () => !("shouldCompact" in policy) ? {
 						messages: [],
 						...await summarize({
-							agentName: options.agent.contract.name,
+							agentName: options.contract.name,
 							context: baseContext,
 							instructions: policy.instructions
 						})
-					} : { messages: await policy.compact(compactionContext) };
+					} : { messages: await policy.compact(compactionContext) });
 					if (checkAbort(ctx.signal)) return;
 					const completed = {
 						generationId,
@@ -2313,7 +2465,7 @@ function createHandlers(options) {
 				}
 			}
 			const currentState = foldAIEvents({
-				reducer: contextReducer[aiStateReducer],
+				reducer: contextReducer,
 				events: generationEvents,
 				state
 			});
@@ -2321,12 +2473,21 @@ function createHandlers(options) {
 				state: currentState,
 				coordinator: promptCoordinatorState
 			});
-			if (policy && "shouldCompact" in policy || generationMessages !== messages || activeCompaction(currentState)?.summary !== activeCompaction(state)?.summary) modelMessages = await modelContext({
+			if (policy && "shouldCompact" in policy || generationMessages !== messages || activeCompaction(currentState)?.summary !== activeCompaction(state)?.summary) modelMessages = await telemetry.span("a2.ai.context", {
+				"a2.contract": options.contract.name,
+				"a2.session_id": ctx.event.sessionId,
+				"a2.ai.context.request_id": requestId,
+				"a2.ai.context.phase": "refresh"
+			}, () => modelContext({
 				messages: generationMessages,
 				state: currentState,
 				tools
+			}));
+			cachePrompt({
+				sessionId: ctx.event.sessionId,
+				generationId,
+				messages: Promise.resolve(modelMessages)
 			});
-			promptCache.set(promptCacheKey(ctx.event.sessionId, generationId), Promise.resolve(modelMessages));
 			if (tracksInput && (inputTokenEstimate === void 0 || compacted)) inputTokenEstimate = await estimateInputTokens({
 				messages: modelMessages,
 				instructions: resolvedInstructions,
@@ -2335,23 +2496,14 @@ function createHandlers(options) {
 			let pendingToolCalls = [];
 			if (checkAbort(ctx.signal)) return;
 			const generateContext = {
-				request: ctx.event,
-				requestId,
-				generationId,
-				responseMessageId,
+				...baseContext,
 				messages: generationMessages,
-				modelMessages,
-				session: resolverContext.session,
-				signal: ctx.signal,
-				model: resolvedModel,
-				tools,
-				...resolvedInstructions === void 0 ? {} : { instructions: resolvedInstructions },
-				generation: options.generation ?? {}
+				modelMessages
 			};
 			const custom = options.generate !== void 0;
 			const updates = consumeGeneration({
 				source: options.generate === void 0 ? await generateWithAISDK({
-					agentName: options.agent.contract.name,
+					agentName: options.contract.name,
 					context: generateContext,
 					messageMetadata: options.messageMetadata
 				}) : { stream: await options.generate(generateContext) },
@@ -2366,11 +2518,7 @@ function createHandlers(options) {
 					continue;
 				}
 				const progress = {
-					requestId,
-					messageId: request.messageId,
-					generationId,
-					responseMessageId,
-					sequence,
+					startIndex,
 					chunks: update.chunks
 				};
 				const lifecycle = await lifecycleEvents({
@@ -2415,6 +2563,7 @@ function createHandlers(options) {
 			if (unresolved.length > 0) throw new Error(`generation ended with unresolved tool authorization for '${unresolved[0].call.toolName}'`);
 			const pendingEvents = await Promise.all(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];
+			forgetPrompt(ctx.event.sessionId, generationId);
 			return [
 				...pendingEvents,
 				completionEvent,
@@ -2431,7 +2580,13 @@ function createHandlers(options) {
 				throw error;
 			}
 			if (checkAbort(ctx.signal)) return;
-			if (!generationStarted) throw error;
+			if (!generationStarted && !resolving) throw error;
+			if (!generationStarted) await control.append({
+				ctx,
+				name: "generation-start",
+				events: await startEvents(startedPayload(resolvedModel))
+			});
+			forgetPrompt(ctx.event.sessionId, generationId);
 			const failed = {
 				requestId,
 				messageId: request.messageId,
@@ -2446,10 +2601,6 @@ function createHandlers(options) {
 			};
 		}
 	};
-	const clearPromptCache = (sessionId) => {
-		const prefix = `${sessionId}\u001f`;
-		for (const key of promptCache.keys()) if (key.startsWith(prefix)) promptCache.delete(key);
-	};
 	return {
 		"ai.model.metadata.requested": { handler: async (ctx) => {
 			const limits = await readModelLimits({
@@ -2474,29 +2625,16 @@ function createHandlers(options) {
 				if ((command.action === "send" || command.action === "steer") && event.id !== command.message.id) throw new A2Error("INVALID_PAYLOAD", "AI input event ID must equal message.id");
 				return "a2.ai.control";
 			},
-			handler: control.handler
+			handler: controlHandler
 		},
 		"ai.work.reported": {
 			lane: "a2.ai.control",
-			handler: control.handler
+			handler: controlHandler
 		},
-		"ai.message.completed": { handler: async (ctx) => {
-			clearPromptCache(ctx.event.sessionId);
-		} },
-		"ai.message.interrupted": { handler: async (ctx) => {
-			clearPromptCache(ctx.event.sessionId);
-		} },
 		"ai.session.closed": {
 			lane: "a2.ai.control",
-			handler: async (ctx) => {
-				clearPromptCache(ctx.event.sessionId);
-				return control.handler(ctx);
-			}
+			handler: controlHandler
 		},
-		"ai.generation.failed": { handler: (ctx) => {
-			promptCache.delete(promptCacheKey(ctx.event.sessionId, ctx.event.payload.generationId));
-			return Promise.resolve();
-		} },
 		"ai.generation.requested": {
 			lane: "a2.ai.model",
 			abortOn: {
@@ -2507,7 +2645,12 @@ function createHandlers(options) {
 				},
 				"ai.session.closed": true
 			},
-			handler: async (ctx) => {
+			handler: (ctx) => telemetry.span("a2.ai.generate", {
+				"a2.contract": options.contract.name,
+				"a2.session_id": ctx.event.sessionId,
+				"a2.ai.generate.request_id": ctx.event.id,
+				"a2.ai.generate.attempt": ctx.attempt
+			}, async () => {
 				try {
 					return control.settled({
 						ctx,
@@ -2523,9 +2666,10 @@ function createHandlers(options) {
 					});
 					throw error;
 				}
-			}
+			})
 		},
 		"ai.tool.execution.requested": {
+			...options.toolLane === void 0 ? {} : { lane: options.toolLane },
 			abortOn: {
 				"ai.control.requested": (event, trigger) => event.payload.action === "stop" && event.payload.turnId === trigger.payload.turnId,
 				"ai.generation.failed": (event, trigger) => event.payload.generationId === trigger.payload.call.generationId,
@@ -2535,16 +2679,40 @@ function createHandlers(options) {
 				},
 				"ai.session.closed": true
 			},
-			handler: handleToolExecution
+			handler: (ctx) => telemetry.span("a2.ai.tool", {
+				"a2.contract": options.contract.name,
+				"a2.session_id": ctx.event.sessionId,
+				"a2.ai.tool.request_id": ctx.event.payload.call.requestId,
+				"a2.ai.tool.call_id": ctx.event.payload.call.toolCallId,
+				"a2.ai.tool.name": ctx.event.payload.call.toolName,
+				"a2.ai.tool.attempt": ctx.attempt
+			}, () => handleToolExecution(ctx))
 		}
 	};
 }
-/** Assemble an A2 server with the built-in agent handlers and app extensions. */
-function createAgentServer(options) {
-	const { agent: definition, model, tools, instructions, generation, maxSteps, messageMetadata, generate, compaction, progress, handlers, ...serverOptions } = options;
+function agent(options) {
+	const { model, tools, instructions, generation, maxSteps, messageMetadata, generate, compaction, progress, toolLane, handlers, ...rest } = options;
+	let contract;
+	let serverOptions;
+	if ("contract" in rest) {
+		const { contract: shared, ...remaining } = rest;
+		if ("name" in remaining) throw new TypeError("agent takes either name or contract, not both");
+		if (!isAgentContract(shared)) throw new TypeError("agent({ contract }) takes an agentContract()");
+		contract = shared;
+		serverOptions = remaining;
+	} else {
+		const { name, events, messageSchema, ...remaining } = rest;
+		contract = agentContract({
+			name,
+			...events === void 0 ? {} : { events },
+			...messageSchema === void 0 ? {} : { messageSchema }
+		});
+		serverOptions = remaining;
+	}
 	const builtIns = createHandlers({
-		agent: definition,
+		contract,
 		model,
+		...serverOptions.telemetry === void 0 ? {} : { telemetry: serverOptions.telemetry },
 		...tools === void 0 ? {} : { tools },
 		...instructions === void 0 ? {} : { instructions },
 		...generation === void 0 ? {} : { generation },
@@ -2552,20 +2720,26 @@ function createAgentServer(options) {
 		...messageMetadata === void 0 ? {} : { messageMetadata },
 		...generate === void 0 ? {} : { generate },
 		...compaction === void 0 ? {} : { compaction },
-		...progress === void 0 ? {} : { progress }
+		...progress === void 0 ? {} : { progress },
+		...toolLane === void 0 ? {} : { toolLane }
 	});
+	for (const type of Object.keys(handlers ?? {})) if (Object.hasOwn(builtIns, type)) throw new TypeError(`agent handles '${type}' itself`);
 	const server = createServer({
 		...serverOptions,
-		contract: definition.contract,
+		contract,
 		handlers: {
 			...builtIns,
 			...handlers
 		}
 	});
-	setServerFetchHooks(server, { validateIngress: validateAgentIngress });
+	const applicationEvents = "contract" in rest;
+	setServerFetchHooks(server, { validateIngress: (context) => validateAgentIngress({
+		context,
+		applicationEvents
+	}) });
 	return server;
 }
 //#endregion
-export { createAgentServer, createHandlers, runWithHandlerContext };
+export { agent, runWithHandlerContext };
 
 //# sourceMappingURL=ai-server.js.map