experimental-a2 0.13.0 → 0.14.0

package/dist/ai.js

@@ -1,13 +1,407 @@
 import { n as validateSync, t as assertSyncSchema } from "./validate-XKT4FSNn.js";
-import { t as contract } from "./contract-48bUMgcL.js";
+import { t as clientStateProjection } from "./reducer-DEMjEY_O.js";
+import { t as contract } from "./contract-CKRg_E4q.js";
 import { l as ambientToolScopeStorage } from "./internal-Dq2qYxou.js";
+import { n as applyControlChanges, t as initialControlState } from "./ai-control-CcD4hh3y.js";
+//#region src/ai-client-state.ts
+const isQueueCommand = (command) => command.action === "send" || command.action === "edit" || command.action === "move" || command.action === "remove" || command.action === "send-now" || command.action === "steer" || command.action === "pause" || command.action === "resume";
+const moveItem = ({ items, inputId, beforeId }) => {
+	const from = items.findIndex((item) => item.id === inputId);
+	if (from < 0 || inputId === beforeId || beforeId !== null && !items.some((item) => item.id === beforeId)) return items;
+	const next = [...items];
+	const [item] = next.splice(from, 1);
+	const to = beforeId === null ? next.length : next.findIndex((entry) => entry.id === beforeId);
+	next.splice(to, 0, item);
+	return next;
+};
+function projectAIClientState(state) {
+	const pending = state.pendingQueueCommands ?? [];
+	if (state.status === "closed") return state;
+	if (pending.length === 0 && !state.inbox.items.some((item) => item.afterStepOf !== void 0)) return state;
+	let messages = state.messages;
+	let { items, paused } = state.inbox;
+	let turnId = state.active?.turnId ?? null;
+	let starting = false;
+	let suspended = state.active?.phase === "paused" || state.active?.phase === "pausing";
+	let messageIds;
+	const show = (message) => {
+		messageIds ??= new Set(messages.map((item) => item.id));
+		if (messageIds.has(message.id)) return;
+		if (messages === state.messages) messages = state.messages.slice();
+		messages.push(message);
+		messageIds.add(message.id);
+	};
+	const admit = () => {
+		if (turnId !== null || paused || items.length === 0) return;
+		let count = 0;
+		for (const item of items) {
+			count += 1;
+			show(item.message);
+			if (item.generate) {
+				turnId = item.id;
+				starting = true;
+				suspended = false;
+				break;
+			}
+		}
+		if (count > 0) items = items.slice(count);
+	};
+	for (const { command } of pending) {
+		switch (command.action) {
+			case "send":
+			case "steer": {
+				if (items.some((item) => item.id === command.message.id) || turnId === command.message.id) break;
+				const item = {
+					...command.action === "steer" ? { afterStepOf: command.turnId } : {},
+					id: command.message.id,
+					revision: 0,
+					message: command.message,
+					generate: command.message.role === "user" && (command.action === "steer" || command.generate !== false)
+				};
+				items = command.action === "steer" ? [item, ...items] : [...items, item];
+				break;
+			}
+			case "edit":
+				items = items.map((item) => item.id === command.message.id && item.revision === command.expectedRevision && item.message.role === command.message.role ? {
+					...item,
+					message: command.message
+				} : item);
+				break;
+			case "move":
+				items = moveItem({
+					items,
+					inputId: command.inputId,
+					beforeId: command.beforeId
+				});
+				break;
+			case "remove":
+				items = items.filter((item) => item.id !== command.inputId);
+				break;
+			case "send-now": {
+				if (turnId !== command.turnId) break;
+				const selected = items.find((item) => item.id === command.inputId);
+				if (!selected || selected.message.role !== "user") break;
+				items = items.map((item) => item.id === selected.id ? {
+					...item,
+					generate: true,
+					...turnId === null ? {} : { afterStepOf: turnId }
+				} : item);
+				items = moveItem({
+					items,
+					inputId: command.inputId,
+					beforeId: items[0]?.id ?? null
+				});
+				break;
+			}
+			case "pause":
+				paused = true;
+				if (command.when === "now") suspended = true;
+				break;
+			case "resume":
+				paused = false;
+				suspended = false;
+		}
+		admit();
+	}
+	items = items.filter((item) => {
+		if (item.afterStepOf === void 0) return true;
+		show(item.message);
+		return false;
+	});
+	return {
+		...state,
+		messages,
+		inbox: {
+			items,
+			paused
+		},
+		starting: starting && !suspended
+	};
+}
+//#endregion
+//#region src/parse-partial-json.ts
+/*!
+* Adapted from AI SDK 7.0.58, packages/ai/src/util/fix-json.ts.
+* Source: https://github.com/vercel/ai, packages/ai/src/util/fix-json.ts.
+* Modified to expose a synchronous partial parser with strict TypeScript types.
+* Also preserves positive exponents in unfinished containers.
+* Copyright 2023 Vercel, Inc.
+* @license Apache-2.0. See src/licenses/Apache-2.0.txt.
+*/
+function parsePartialJSON(text) {
+	if (text === void 0 || text.trim() === "") return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		try {
+			return JSON.parse(repairPartialJSON(text));
+		} catch {
+			return;
+		}
+	}
+}
+const isHexDigit = (char) => char >= "0" && char <= "9" || char >= "A" && char <= "F" || char >= "a" && char <= "f";
+function repairPartialJSON(input) {
+	const stack = ["ROOT"];
+	let lastValidIndex = -1;
+	let literalStart = null;
+	let unicodeEscapeDigits = 0;
+	function processValueStart(char, i, swapState) {
+		switch (char) {
+			case "\"":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_STRING");
+				break;
+			case "f":
+			case "t":
+			case "n":
+				lastValidIndex = i;
+				literalStart = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_LITERAL");
+				break;
+			case "-":
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_NUMBER");
+				break;
+			case "0":
+			case "1":
+			case "2":
+			case "3":
+			case "4":
+			case "5":
+			case "6":
+			case "7":
+			case "8":
+			case "9":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_NUMBER");
+				break;
+			case "{":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_OBJECT_START");
+				break;
+			case "[":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_ARRAY_START");
+		}
+	}
+	function processAfterObjectValue(char, i) {
+		switch (char) {
+			case ",":
+				stack.pop();
+				stack.push("INSIDE_OBJECT_AFTER_COMMA");
+				break;
+			case "}":
+				lastValidIndex = i;
+				stack.pop();
+		}
+	}
+	function processAfterArrayValue(char, i) {
+		switch (char) {
+			case ",":
+				stack.pop();
+				stack.push("INSIDE_ARRAY_AFTER_COMMA");
+				break;
+			case "]":
+				lastValidIndex = i;
+				stack.pop();
+		}
+	}
+	for (let i = 0; i < input.length; i++) {
+		const char = input[i];
+		switch (stack[stack.length - 1]) {
+			case "ROOT":
+				processValueStart(char, i, "FINISH");
+				break;
+			case "INSIDE_OBJECT_START":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_KEY");
+						break;
+					case "}":
+						lastValidIndex = i;
+						stack.pop();
+				}
+				break;
+			case "INSIDE_OBJECT_AFTER_COMMA":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_KEY");
+				}
+				break;
+			case "INSIDE_OBJECT_KEY":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_AFTER_KEY");
+				}
+				break;
+			case "INSIDE_OBJECT_AFTER_KEY":
+				switch (char) {
+					case ":":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_BEFORE_VALUE");
+				}
+				break;
+			case "INSIDE_OBJECT_BEFORE_VALUE":
+				processValueStart(char, i, "INSIDE_OBJECT_AFTER_VALUE");
+				break;
+			case "INSIDE_OBJECT_AFTER_VALUE":
+				processAfterObjectValue(char, i);
+				break;
+			case "INSIDE_STRING":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						lastValidIndex = i;
+						break;
+					case "\\":
+						stack.push("INSIDE_STRING_ESCAPE");
+						break;
+					default: lastValidIndex = i;
+				}
+				break;
+			case "INSIDE_ARRAY_START":
+				switch (char) {
+					case "]":
+						lastValidIndex = i;
+						stack.pop();
+						break;
+					default:
+						lastValidIndex = i;
+						processValueStart(char, i, "INSIDE_ARRAY_AFTER_VALUE");
+				}
+				break;
+			case "INSIDE_ARRAY_AFTER_VALUE":
+				switch (char) {
+					case ",":
+						stack.pop();
+						stack.push("INSIDE_ARRAY_AFTER_COMMA");
+						break;
+					case "]":
+						lastValidIndex = i;
+						stack.pop();
+						break;
+					default: lastValidIndex = i;
+				}
+				break;
+			case "INSIDE_ARRAY_AFTER_COMMA":
+				processValueStart(char, i, "INSIDE_ARRAY_AFTER_VALUE");
+				break;
+			case "INSIDE_STRING_ESCAPE":
+				stack.pop();
+				if (char === "u") {
+					unicodeEscapeDigits = 0;
+					stack.push("INSIDE_STRING_UNICODE_ESCAPE");
+				} else lastValidIndex = i;
+				break;
+			case "INSIDE_STRING_UNICODE_ESCAPE":
+				if (isHexDigit(char)) {
+					unicodeEscapeDigits++;
+					if (unicodeEscapeDigits === 4) {
+						stack.pop();
+						lastValidIndex = i;
+					}
+				}
+				break;
+			case "INSIDE_NUMBER":
+				switch (char) {
+					case "0":
+					case "1":
+					case "2":
+					case "3":
+					case "4":
+					case "5":
+					case "6":
+					case "7":
+					case "8":
+					case "9":
+						lastValidIndex = i;
+						break;
+					case "e":
+					case "E":
+					case "-":
+					case "+":
+					case ".": break;
+					case ",":
+						stack.pop();
+						if (stack[stack.length - 1] === "INSIDE_ARRAY_AFTER_VALUE") processAfterArrayValue(char, i);
+						if (stack[stack.length - 1] === "INSIDE_OBJECT_AFTER_VALUE") processAfterObjectValue(char, i);
+						break;
+					case "}":
+						stack.pop();
+						if (stack[stack.length - 1] === "INSIDE_OBJECT_AFTER_VALUE") processAfterObjectValue(char, i);
+						break;
+					case "]":
+						stack.pop();
+						if (stack[stack.length - 1] === "INSIDE_ARRAY_AFTER_VALUE") processAfterArrayValue(char, i);
+						break;
+					default: stack.pop();
+				}
+				break;
+			case "INSIDE_LITERAL": {
+				const partialLiteral = input.substring(literalStart, i + 1);
+				if (!"false".startsWith(partialLiteral) && !"true".startsWith(partialLiteral) && !"null".startsWith(partialLiteral)) {
+					stack.pop();
+					if (stack[stack.length - 1] === "INSIDE_OBJECT_AFTER_VALUE") processAfterObjectValue(char, i);
+					else if (stack[stack.length - 1] === "INSIDE_ARRAY_AFTER_VALUE") processAfterArrayValue(char, i);
+				} else lastValidIndex = i;
+				break;
+			}
+		}
+	}
+	let result = input.slice(0, lastValidIndex + 1);
+	for (let i = stack.length - 1; i >= 0; i--) switch (stack[i]) {
+		case "INSIDE_STRING":
+			result += "\"";
+			break;
+		case "INSIDE_OBJECT_KEY":
+		case "INSIDE_OBJECT_AFTER_KEY":
+		case "INSIDE_OBJECT_AFTER_COMMA":
+		case "INSIDE_OBJECT_START":
+		case "INSIDE_OBJECT_BEFORE_VALUE":
+		case "INSIDE_OBJECT_AFTER_VALUE":
+			result += "}";
+			break;
+		case "INSIDE_ARRAY_START":
+		case "INSIDE_ARRAY_AFTER_COMMA":
+		case "INSIDE_ARRAY_AFTER_VALUE":
+			result += "]";
+			break;
+		case "INSIDE_LITERAL": {
+			const partialLiteral = input.substring(literalStart, input.length);
+			if ("true".startsWith(partialLiteral)) result += "true".slice(partialLiteral.length);
+			else if ("false".startsWith(partialLiteral)) result += "false".slice(partialLiteral.length);
+			else if ("null".startsWith(partialLiteral)) result += "null".slice(partialLiteral.length);
+		}
+	}
+	return result;
+}
+//#endregion
 //#region src/ai-projector.ts
 const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const cloneMessage = (messageId, base) => structuredClone(base ?? {
+const cloneMessage = (messageId, base) => base === void 0 ? {
 	id: messageId,
 	role: "assistant",
 	parts: []
-});
+} : {
+	...base,
+	id: messageId,
+	parts: base.parts.map((part) => ({ ...part }))
+};
 const currentStepParts = (parts) => {
 	let start = parts.length - 1;
 	while (start >= 0 && parts[start]?.["type"] !== "step-start") start -= 1;
@@ -60,21 +454,16 @@ const mergeMetadata = (current, update) => {
 		...update
 	} : update;
 };
-const parseCompleteJSON = (value) => {
-	try {
-		return JSON.parse(value);
-	} catch {
-		return;
-	}
-};
-/** Internal synchronous counterpart of the AI SDK UI message stream fold. */
 function projectUIMessage(options) {
+	return projectUIMessageStream(options).message;
+}
+function projectUIMessageStream(options) {
 	const message = cloneMessage(options.messageId, options.base);
 	const record = message;
 	const parts = message.parts;
-	const activeText = /* @__PURE__ */ new Map();
-	const activeReasoning = /* @__PURE__ */ new Map();
-	const partialTools = /* @__PURE__ */ new Map();
+	const activeText = new Map(Object.entries(options.cursor?.text ?? {}).map(([id, index]) => [id, parts[index]]));
+	const activeReasoning = new Map(Object.entries(options.cursor?.reasoning ?? {}).map(([id, index]) => [id, parts[index]]));
+	const partialTools = new Map(Object.entries(options.cursor?.tools ?? {}).map(([id, partial]) => [id, { ...partial }]));
 	for (const chunk of options.chunks) switch (chunk.type) {
 		case "text-start": {
 			const part = {
@@ -213,7 +602,7 @@ function projectUIMessage(options) {
 				toolName: partial.toolName,
 				dynamic: partial.dynamic,
 				state: "input-streaming",
-				input: parseCompleteJSON(partial.text),
+				input: parsePartialJSON(partial.text),
 				providerExecuted: partial.providerExecuted,
 				providerMetadata: partial.providerMetadata,
 				toolMetadata: partial.toolMetadata,
@@ -333,7 +722,6 @@ function projectUIMessage(options) {
 			activeReasoning.clear();
 			break;
 		case "start":
-			if (chunk.messageId !== void 0) record["id"] = chunk.messageId;
 			if (chunk.messageMetadata !== void 0 && chunk.messageMetadata !== null) record["metadata"] = mergeMetadata(record["metadata"], chunk.messageMetadata);
 			break;
 		case "finish":
@@ -355,10 +743,28 @@ function projectUIMessage(options) {
 			});
 		}
 	}
-	return message;
+	const indexes = new Map(parts.map((part, index) => [part, index]));
+	return {
+		message,
+		cursor: {
+			text: Object.fromEntries([...activeText].map(([id, part]) => [id, indexes.get(part)])),
+			reasoning: Object.fromEntries([...activeReasoning].map(([id, part]) => [id, indexes.get(part)])),
+			tools: Object.fromEntries(partialTools)
+		}
+	};
+}
+function pauseUIMessage(options) {
+	const next = structuredClone(options.message);
+	next.parts = next.parts.filter((part) => !("toolCallId" in part && !options.toolCallIds.has(part.toolCallId)));
+	for (const part of next.parts) if ((part.type === "text" || part.type === "reasoning") && part.state === "streaming") part.state = "done";
+	return next;
 }
 function interruptUIMessage(message, toolError = "Tool execution was interrupted.") {
 	const next = structuredClone(message);
+	next.parts = next.parts.filter((value) => {
+		const part = value;
+		return !isToolPart(part) || part["state"] !== "input-streaming";
+	});
 	for (const value of next.parts) {
 		if (value["type"] === "text" || value["type"] === "reasoning") {
 			if (value["state"] === "streaming") value["state"] = "done";
@@ -380,7 +786,7 @@ function interruptUIMessage(message, toolError = "Tool execution was interrupted
 			value["errorText"] = toolError;
 			continue;
 		}
-		if (state === "input-streaming" || state === "input-available" || state === "approval-requested" || state === "approval-responded") {
+		if (state === "input-available" || state === "approval-requested" || state === "approval-responded") {
 			if (state === "approval-requested") delete value["approval"];
 			value["state"] = "output-error";
 			value["errorText"] = toolError;
@@ -389,6 +795,63 @@ function interruptUIMessage(message, toolError = "Tool execution was interrupted
 	return next;
 }
 //#endregion
+//#region src/ai-progress-batches.ts
+const PAGE_SIZE = 64;
+const appendProgressBatch = ({ batches, batch }) => {
+	if (batches.tail.length < PAGE_SIZE) return {
+		...batches,
+		length: batches.length + 1,
+		tail: [...batches.tail, batch]
+	};
+	const blocks = [...batches.blocks];
+	let block = batches.tail;
+	let level = 0;
+	for (;;) {
+		const left = blocks[level];
+		if (left == null) break;
+		block = {
+			left,
+			right: block
+		};
+		blocks[level] = null;
+		level += 1;
+	}
+	blocks[level] = block;
+	return {
+		length: batches.length + 1,
+		tail: [batch],
+		blocks
+	};
+};
+const progressBatches = (items = []) => {
+	let batches = {
+		length: 0,
+		tail: [],
+		blocks: []
+	};
+	for (const batch of items) batches = appendProgressBatch({
+		batches,
+		batch
+	});
+	return batches;
+};
+const flattenProgressBatches = (batches) => {
+	const items = [];
+	const visit = (block) => {
+		if (Array.isArray(block)) items.push(...block);
+		else {
+			visit(block.left);
+			visit(block.right);
+		}
+	};
+	for (let level = batches.blocks.length - 1; level >= 0; level -= 1) {
+		const block = batches.blocks[level];
+		if (block) visit(block);
+	}
+	items.push(...batches.tail);
+	return items;
+};
+//#endregion
 //#region src/ai.ts
 const issue = (message) => ({ issues: [{ message }] });
 const schema = (label, parse) => ({ "~standard": {
@@ -467,13 +930,79 @@ const compactionPayloadSchema = (messageSchema) => schema("ai.compaction.complet
 function createEvents(options) {
 	const messageSchema = options?.messageSchema;
 	if (messageSchema) assertSyncSchema(messageSchema, "the AI message schema");
-	return {
+	const definition = {
+		"ai.control.requested": schema("ai.control.requested", (value) => {
+			if (!isRecord(value) || !isJSONCompatible(value)) return issue("invalid AI command");
+			const action = value["action"];
+			const forwarded = {
+				approval: ["ai.approval.responded", "response"],
+				"tool-result": ["ai.tool.result", "result"],
+				input: ["ai.input.responded", "response"],
+				"request-input": ["ai.input.requested", "request"],
+				retry: ["ai.retry.requested", "request"],
+				interrupt: ["ai.message.interrupted", "request"]
+			};
+			if (typeof action === "string" && Object.hasOwn(forwarded, action)) {
+				const [type, key] = forwarded[action];
+				const payload = validateSync(definition[type], value[key], "AI command");
+				if (payload.issues) return { issues: payload.issues };
+				return { value: {
+					action,
+					[key]: payload.value
+				} };
+			}
+			if (action === "send" || action === "edit" || action === "steer") {
+				const parsed = validateMessage(value["message"], messageSchema);
+				if (parsed.issues) return parsed;
+				if (action === "edit" && (!Number.isSafeInteger(value["expectedRevision"]) || Number(value["expectedRevision"]) < 0) || action === "steer" && (!stringField(value, "turnId") || !optionalIndexField(value, "lastSeenIndex")) || action === "send" && value["generate"] !== void 0 && typeof value["generate"] !== "boolean") return issue("invalid AI command");
+				return { value: {
+					...value,
+					message: parsed.value
+				} };
+			}
+			if (action === "remove" && stringField(value, "inputId") || action === "send-now" && stringField(value, "inputId") && (value["turnId"] === null || stringField(value, "turnId")) && optionalIndexField(value, "lastSeenIndex") || action === "move" && stringField(value, "inputId") && (value["beforeId"] === null || stringField(value, "beforeId")) || action === "stop" && stringField(value, "turnId") && optionalIndexField(value, "lastSeenIndex") || action === "pause" && (value["when"] === "now" || value["when"] === "after-turn") || action === "resume") return { value };
+			return issue("invalid AI command");
+		}),
+		"ai.control.committed": jsonObject("ai.control.committed", (value) => Array.isArray(value["changes"]) && isRecord(value["view"])),
+		"ai.control.decided": jsonObject("ai.control.decided", (value) => stringField(value, "commandId") && (value["outcome"] === "applied" || value["outcome"] === "rejected")),
+		"ai.work.reported": schema("ai.work.reported", (value) => {
+			if (!isRecord(value) || !isJSONCompatible(value) || !stringField(value, "workId") || !stringField(value, "turnId") || typeof value["version"] !== "number" || !optionalIndexField(value, "version") || typeof value["attempt"] !== "number" || !Number.isSafeInteger(value["attempt"]) || value["attempt"] < 1 || typeof value["settled"] !== "boolean" || value["kind"] !== "model" && value["kind"] !== "tool" || !Array.isArray(value["events"])) return issue("invalid AI work report");
+			const allowed = /* @__PURE__ */ new Set([
+				"ai.generation.started",
+				"ai.generation.completed",
+				"ai.generation.failed",
+				"ai.tool.called",
+				"ai.tool.result",
+				"ai.approval.requested",
+				"ai.approval.responded",
+				"ai.compaction.requested",
+				"ai.compaction.completed",
+				"ai.model.metadata.requested"
+			]);
+			const events = [];
+			for (const event of value["events"]) {
+				if (!isRecord(event) || !stringField(event, "id") || typeof event["type"] !== "string" || !allowed.has(event["type"]) || value["kind"] === "tool" && event["type"] !== "ai.tool.result") return issue("invalid AI work fact");
+				const parsed = validateSync(definition[event["type"]], event["payload"], "AI work fact");
+				if (parsed.issues) return { issues: parsed.issues };
+				events.push({
+					id: event["id"],
+					type: event["type"],
+					payload: parsed.value
+				});
+			}
+			return { value: {
+				...value,
+				events
+			} };
+		}),
+		"ai.tool.execution.requested": jsonObject("ai.tool.execution.requested", (value) => stringField(value, "turnId") && optionalIndexField(value, "version") && isRecord(value["call"]) && isRecord(value["generation"])),
+		"ai.generation.paused": jsonObject("ai.generation.paused", (value) => stringField(value, "generationId") && stringField(value, "messageId")),
 		"ai.session.created": jsonObject("ai.session.created", () => true),
 		"ai.session.closed": jsonObject("ai.session.closed", (value) => optionalStringField(value, "reason")),
 		"ai.message.created": messagePayloadSchema(messageSchema),
 		"ai.message.completed": jsonObject("ai.message.completed", (value) => stringField(value, "messageId")),
 		"ai.message.interrupted": jsonObject("ai.message.interrupted", (value) => stringField(value, "messageId") && (stringField(value, "generationId") && value["requestId"] === void 0 || stringField(value, "requestId") && value["generationId"] === void 0) && optionalStringField(value, "reason") && (value["lastSeenIndex"] === void 0 || typeof value["lastSeenIndex"] === "number" && Number.isInteger(value["lastSeenIndex"]) && value["lastSeenIndex"] >= 0)),
-		"ai.generation.requested": jsonObject("ai.generation.requested", (value) => stringField(value, "messageId") && optionalStringField(value, "responseMessageId") && (value["reason"] === "message" || value["reason"] === "tool" || value["reason"] === "input" || value["reason"] === "retry")),
+		"ai.generation.requested": jsonObject("ai.generation.requested", (value) => stringField(value, "messageId") && optionalStringField(value, "responseMessageId") && (value["reason"] === "message" || value["reason"] === "tool" || value["reason"] === "input" || value["reason"] === "retry" || value["reason"] === "resume")),
 		"ai.retry.requested": jsonObject("ai.retry.requested", (value) => stringField(value, "messageId") && stringField(value, "responseMessageId") && stringField(value, "retryId")),
 		"ai.generation.started": jsonObject("ai.generation.started", (value) => stringField(value, "requestId") && stringField(value, "messageId") && stringField(value, "generationId") && stringField(value, "responseMessageId") && typeof value["attempt"] === "number" && Number.isInteger(value["attempt"]) && value["attempt"] > 0 && stringField(value, "model") && optionalIndexField(value, "promptThroughIndex")),
 		"ai.generation.progress": progressPayloadSchema,
@@ -490,9 +1019,15 @@ function createEvents(options) {
 		"ai.model.metadata.requested": jsonObject("ai.model.metadata.requested", (value) => stringField(value, "modelId")),
 		"ai.model.metadata.resolved": jsonObject("ai.model.metadata.resolved", (value) => stringField(value, "modelId") && (value["limits"] === null || isRecord(value["limits"]) && typeof value["limits"]["contextWindow"] === "number" && Number.isSafeInteger(value["limits"]["contextWindow"]) && value["limits"]["contextWindow"] > 0 && typeof value["limits"]["maxOutputTokens"] === "number" && Number.isSafeInteger(value["limits"]["maxOutputTokens"]) && value["limits"]["maxOutputTokens"] > 0))
 	};
+	return definition;
 }
 const events = createEvents();
 const initialState = () => ({
+	inbox: initialControlState().inbox,
+	pendingQueueCommands: [],
+	active: null,
+	starting: false,
+	receipt: null,
 	session: { created: false },
 	messages: [],
 	status: "idle",
@@ -516,6 +1051,17 @@ const upsertMessage = (messages, message) => {
 	next[index] = message;
 	return next;
 };
+const upsertResponse = (options) => {
+	const { messages, message, inputId } = options;
+	if (messages.some((item) => item.id === message.id)) return upsertMessage(messages, message);
+	const inputIndex = messages.findIndex((item) => item.id === inputId);
+	if (inputIndex === -1) return [...messages, message];
+	return [
+		...messages.slice(0, inputIndex + 1),
+		message,
+		...messages.slice(inputIndex + 1)
+	];
+};
 const answerApproval = (messages, response) => messages.map((message) => {
 	if (message.id !== response.messageId) return message;
 	let changed = false;
@@ -601,8 +1147,8 @@ const isStaleGeneration = (state, messageId, generationId) => {
 	const current = state.responseGenerationIds[messageId];
 	return current !== void 0 && current !== generationId;
 };
-const projectedMessage = (projection) => {
-	const projectionEvents = [...projection.batches];
+const projectedMessageStream = (projection) => {
+	const projectionEvents = flattenProgressBatches(projection.batches);
 	for (const event of projection.toolEvents) if (event.type === "ai.tool.result") projectionEvents.push({
 		index: event.index,
 		chunks: [toolResultChunk(event.payload)]
@@ -611,12 +1157,20 @@ const projectedMessage = (projection) => {
 		index: event.index,
 		chunks: [event.type === "ai.approval.requested" ? approvalRequestedChunk(event.payload) : approvalRespondedChunk(event.payload)]
 	});
-	return projectUIMessage({
+	return projectUIMessageStream({
 		messageId: projection.responseMessageId,
 		...projection.baseMessage === void 0 ? {} : { base: projection.baseMessage },
 		chunks: projectionEvents.toSorted((left, right) => left.index - right.index).flatMap((event) => event.chunks)
 	});
 };
+const projectedMessage = (projection) => projectedMessageStream(projection).message;
+const projectedResponse = (options) => {
+	const message = projectedMessage(options.projection);
+	return options.state.pausedGenerationIds?.[options.projection.generationId] ? pauseUIMessage({
+		message,
+		toolCallIds: new Set(options.state.tools.map((tool) => tool.toolCallId))
+	}) : message;
+};
 const reduceToolActivity = (tools, event) => {
 	if (event.type === "ai.tool.called") {
 		const payload = event.payload;
@@ -687,7 +1241,7 @@ const interruptGenerationProjection = (state, generationId, responseMessageId, c
 	if (projection === null) return null;
 	const retained = {
 		...projection,
-		batches: projection.batches.filter((batch) => batch.index <= cutoff),
+		batches: progressBatches(flattenProgressBatches(projection.batches).filter((batch) => batch.index <= cutoff)),
 		toolEvents: projection.toolEvents.filter((toolEvent) => toolEvent.index <= cutoff),
 		approvalEvents: projection.approvalEvents.filter((approvalEvent) => approvalEvent.index <= cutoff)
 	};
@@ -695,7 +1249,7 @@ const interruptGenerationProjection = (state, generationId, responseMessageId, c
 	const restored = restoreGenerationBase(state, generationId, responseMessageId, "interrupted");
 	return {
 		...restored,
-		messages: shouldProject ? upsertMessage(restored.messages, interruptUIMessage(projectedMessage(retained))) : restored.messages,
+		messages: shouldProject ? upsertMessage(state.messages, interruptUIMessage(projectedMessage(retained))) : restored.messages,
 		tools: stopGenerationTools(projectedTools(retained), generationId, responseMessageId, "Tool execution was interrupted."),
 		usage: projection.completionIndex === void 0 || projection.completionIndex <= cutoff ? restored.usage : restored.usage.filter((entry) => entry.generationId !== generationId)
 	};
@@ -714,6 +1268,76 @@ const terminalGenerationReason = (state, generationId) => {
 function reduceAIState(state, event) {
 	if (state.status === "closed") return state;
 	switch (event.type) {
+		case "ai.control.requested": {
+			const command = event.payload;
+			if (!event.id || !isQueueCommand(command)) return state;
+			const pending = state.pendingQueueCommands ?? [];
+			if (pending.some((item) => item.commandId === event.id)) return state;
+			if ((command.action === "send" || command.action === "steer") && (state.messages.some((message) => message.id === command.message.id) || state.inbox.items.some((item) => item.id === command.message.id))) return state;
+			return {
+				...state,
+				pendingQueueCommands: [...pending, {
+					commandId: event.id,
+					command
+				}]
+			};
+		}
+		case "ai.control.committed": {
+			const commit = event.payload;
+			const visible = applyControlChanges({
+				state: {
+					inbox: state.inbox,
+					active: state.active
+				},
+				changes: commit.changes.filter((change) => change.path[0] === "inbox" || change.path[0] === "active")
+			});
+			const { phase } = commit.view;
+			const status = commit.view.closed ? "closed" : phase === "paused" || phase === "pausing" || commit.view.paused && phase === null ? "paused" : phase === "failed" ? "failed" : phase === "starting" || phase === "generating" ? "generating" : phase ? "waiting" : "idle";
+			return {
+				...state,
+				...visible,
+				status,
+				activeRequestId: commit.view.requestId,
+				activeResponseMessageId: commit.view.responseMessageId
+			};
+		}
+		case "ai.control.decided": {
+			const receipt = event.payload;
+			if (receipt.work) return state;
+			const pending = state.pendingQueueCommands ?? [];
+			const settled = pending.find((item) => item.commandId === receipt.commandId);
+			return {
+				...state,
+				receipt,
+				...settled === void 0 ? {} : { pendingQueueCommands: pending.filter((item) => item.commandId !== receipt.commandId) }
+			};
+		}
+		case "ai.generation.paused": {
+			const payload = event.payload;
+			const toolCallIds = new Set(state.tools.filter((tool) => tool.messageId === payload.messageId).map((tool) => tool.toolCallId));
+			const projection = state.activeProjection;
+			return {
+				...state,
+				activeGeneration: null,
+				activeProjection: projection?.generationId === payload.generationId ? {
+					...projection,
+					cursor: null,
+					batches: progressBatches(flattenProgressBatches(projection.batches).map((batch) => ({
+						index: batch.index,
+						chunks: batch.chunks.filter((chunk) => !("toolCallId" in chunk) || toolCallIds.has(chunk.toolCallId))
+					})))
+				} : projection,
+				compaction: state.compaction?.status === "running" ? projection?.baseCompaction ?? null : state.compaction,
+				messages: state.messages.map((message) => message.id === payload.messageId ? pauseUIMessage({
+					message,
+					toolCallIds
+				}) : message),
+				pausedGenerationIds: {
+					...state.pausedGenerationIds,
+					[payload.generationId]: true
+				}
+			};
+		}
 		case "ai.model.metadata.requested": {
 			const { modelId } = event.payload;
 			if (Object.hasOwn(state.modelMetadata, modelId)) return state;
@@ -750,6 +1374,12 @@ function reduceAIState(state, event) {
 		}
 		case "ai.session.closed": return {
 			...state,
+			active: null,
+			inbox: {
+				paused: true,
+				items: []
+			},
+			pendingQueueCommands: [],
 			status: "closed",
 			compaction: state.compaction?.status === "running" ? state.activeProjection?.baseCompaction ?? null : state.compaction,
 			activeGeneration: null,
@@ -761,7 +1391,11 @@ function reduceAIState(state, event) {
 			const { message } = event.payload;
 			return {
 				...state,
-				messages: upsertMessage(state.messages, message)
+				messages: upsertMessage(state.messages, message),
+				activeProjection: state.activeProjection?.responseMessageId === message.id ? {
+					...state.activeProjection,
+					cursor: null
+				} : state.activeProjection
 			};
 		}
 		case "ai.message.completed": {
@@ -792,7 +1426,7 @@ function reduceAIState(state, event) {
 			const ownerRequestId = ownerGenerationId === void 0 ? void 0 : generationRequestId(ownerGenerationId);
 			const requestId = event.id;
 			if (requestId !== void 0 && state.terminalRequestIds?.[requestId] === true) return state;
-			if (!(payload.reason === "message" || (payload.reason === "tool" ? ownerGenerationId !== void 0 && requestId === `ai.generate:tools:${ownerGenerationId}` && state.activeRequestId === ownerRequestId && state.status !== "failed" : payload.reason === "retry" ? state.status === "failed" : ownerGenerationId !== void 0 && requestId?.startsWith(`ai.generate:input:${encodeURIComponent(responseMessageId)}:${encodeURIComponent(ownerGenerationId)}:`) === true && state.activeRequestId === ownerRequestId && state.status !== "failed"))) return state;
+			if (!(payload.control !== void 0 && state.activeRequestId === event.id || payload.reason === "message" || (payload.reason === "tool" ? ownerGenerationId !== void 0 && requestId === `ai.generate:tools:${ownerGenerationId}` && state.activeRequestId === ownerRequestId && state.status !== "failed" : payload.reason === "retry" ? state.status === "failed" : ownerGenerationId !== void 0 && requestId?.startsWith(`ai.generate:input:${encodeURIComponent(responseMessageId)}:${encodeURIComponent(ownerGenerationId)}:`) === true && state.activeRequestId === ownerRequestId && state.status !== "failed"))) return state;
 			return {
 				...state,
 				messages: payload.reason === "retry" && payload.responseMessageId !== void 0 ? state.messages.filter((message) => message.id !== payload.responseMessageId) : state.messages,
@@ -828,9 +1462,10 @@ function reduceAIState(state, event) {
 				activeProjection: {
 					generationId: payload.generationId,
 					responseMessageId: payload.responseMessageId,
+					promptThroughIndex: payload.promptThroughIndex ?? event.index - 1,
 					...baseMessage === void 0 ? {} : { baseMessage },
 					baseCompaction: baseState.compaction,
-					batches: [],
+					batches: progressBatches(),
 					baseTools: baseState.tools,
 					toolEvents: [],
 					approvalEvents: []
@@ -840,19 +1475,43 @@ function reduceAIState(state, event) {
 		}
 		case "ai.generation.progress": {
 			const payload = event.payload;
+			if (state.pausedGenerationIds?.[payload.generationId]) return state;
 			if (terminalGenerationReason(state, payload.generationId) !== void 0) return state;
 			const activeProjection = state.activeProjection;
 			if (state.activeGeneration?.generationId !== payload.generationId || activeProjection?.generationId !== payload.generationId) return state;
+			const ordered = event.index > (activeProjection.batches.tail.at(-1)?.index ?? -1);
 			const projection = {
 				...activeProjection,
-				batches: [...activeProjection.batches.filter((batch) => batch.index !== event.index), {
+				batches: ordered ? appendProgressBatch({
+					batches: activeProjection.batches,
+					batch: {
+						index: event.index,
+						chunks: payload.chunks
+					}
+				}) : progressBatches([...flattenProgressBatches(activeProjection.batches).filter((batch) => batch.index !== event.index), {
 					index: event.index,
 					chunks: payload.chunks
-				}].toSorted((left, right) => left.index - right.index)
+				}].toSorted((left, right) => left.index - right.index))
+			};
+			const base = state.messages.find((message) => message.id === projection.responseMessageId);
+			const incremental = base !== void 0 && activeProjection.cursor != null && event.index > activeProjection.cursor.throughIndex;
+			const projected = incremental ? projectUIMessageStream({
+				messageId: projection.responseMessageId,
+				base,
+				cursor: activeProjection.cursor.stream,
+				chunks: payload.chunks
+			}) : projectedMessageStream(projection);
+			projection.cursor = {
+				throughIndex: incremental ? event.index : Math.max(event.index, projection.batches.tail.at(-1)?.index ?? 0, projection.toolEvents.reduce((index, entry) => Math.max(index, entry.index), 0), projection.approvalEvents.reduce((index, entry) => Math.max(index, entry.index), 0)),
+				stream: projected.cursor
 			};
 			return {
 				...state,
-				messages: upsertMessage(state.messages, projectedMessage(projection)),
+				messages: upsertResponse({
+					messages: state.messages,
+					message: projected.message,
+					inputId: state.activeGeneration.messageId
+				}),
 				activeProjection: projection,
 				status: "generating"
 			};
@@ -1051,13 +1710,17 @@ function reduceAIState(state, event) {
 			}
 			const activeProjection = {
 				...projection,
+				cursor: null,
 				toolEvents: [...projection.toolEvents, {
 					index: event.index,
 					type: "ai.tool.result",
 					payload
 				}]
 			};
-			const projected = projectedMessage(activeProjection);
+			const projected = projectedResponse({
+				state,
+				projection: activeProjection
+			});
 			const tools = projectedTools(activeProjection);
 			const failureError = state.error ?? "Generation failed.";
 			const next = {
@@ -1078,6 +1741,7 @@ function reduceAIState(state, event) {
 			if (state.tools.some((activity) => activity.generationId === payload.generationId && activity.toolCallId === payload.toolCallId && activity.status === "failed" && state.activeGeneration?.generationId !== payload.generationId)) return state;
 			const activeProjection = projection?.generationId === payload.generationId ? {
 				...projection,
+				cursor: null,
 				approvalEvents: [...projection.approvalEvents, {
 					index: event.index,
 					type: "ai.approval.requested",
@@ -1086,7 +1750,10 @@ function reduceAIState(state, event) {
 			} : projection;
 			const next = {
 				...state,
-				messages: activeProjection === null || activeProjection === projection ? projectMessageChunks(state.messages, payload.messageId, [approvalRequestedChunk(payload)]) : upsertMessage(state.messages, projectedMessage(activeProjection)),
+				messages: activeProjection === null || activeProjection === projection ? projectMessageChunks(state.messages, payload.messageId, [approvalRequestedChunk(payload)]) : upsertMessage(state.messages, projectedResponse({
+					state,
+					projection: activeProjection
+				})),
 				activeProjection,
 				pendingApprovals: payload.isAutomatic === true ? state.pendingApprovals : [...state.pendingApprovals.filter((approval) => approval.approvalId !== payload.approvalId || approval.messageId !== payload.messageId), payload]
 			};
@@ -1104,6 +1771,7 @@ function reduceAIState(state, event) {
 			if (state.status === "failed" && pendingRequest === void 0 && activeRequest === void 0) return state;
 			const activeProjection = projection !== null && activeRequest !== void 0 ? {
 				...projection,
+				cursor: null,
 				approvalEvents: [...projection.approvalEvents, {
 					index: event.index,
 					type: "ai.approval.responded",
@@ -1112,8 +1780,14 @@ function reduceAIState(state, event) {
 			} : projection;
 			const next = {
 				...state,
-				messages: activeProjection === null || activeProjection === projection ? answerApproval(state.messages, payload) : upsertMessage(state.messages, projectedMessage(activeProjection)),
-				activeProjection,
+				messages: activeProjection === null || activeProjection === projection ? answerApproval(state.messages, payload) : upsertMessage(state.messages, projectedResponse({
+					state,
+					projection: activeProjection
+				})),
+				activeProjection: activeProjection === null ? null : {
+					...activeProjection,
+					cursor: null
+				},
 				pendingApprovals: state.pendingApprovals.filter((approval) => approval.approvalId !== payload.approvalId || approval.messageId !== payload.messageId || approval.generationId !== payload.generationId)
 			};
 			return {
@@ -1163,7 +1837,8 @@ function reduceAIState(state, event) {
 				...state,
 				compaction: {
 					status: "completed",
-					...payload
+					...payload,
+					throughIndex: payload.throughIndex ?? state.activeProjection.promptThroughIndex
 				}
 			};
 		}
@@ -1178,62 +1853,105 @@ function deriveUIMessages(history) {
 }
 /** Build the standard AI state projection for any contract containing the protocol. */
 function createReducer(options) {
-	return options.contract.reducer({
-		name: options.name ?? "a2.ai.state.v10",
-		initialState: initialState()
-	}).fold((state, event) => reduceAIState(state, event));
+	return {
+		...options.contract.reducer({
+			name: options.name ?? "a2.ai.state.v17",
+			initialState: initialState()
+		}).fold((state, event) => reduceAIState(state, event)),
+		[clientStateProjection]: projectAIClientState
+	};
 }
+const commandInput = (payload) => [{
+	type: "ai.control.requested",
+	payload
+}];
 const messageInput = (message, generate) => [{
-	type: "ai.message.created",
+	type: "ai.control.requested",
 	id: `ai.message:${message.id}`,
 	payload: {
+		action: "send",
 		message,
 		...generate === false ? { generate: false } : {}
 	}
 }];
 /** Pure append inputs for the built-in AI protocol. */
 const inputs = {
+	toolResult: (result) => commandInput({
+		action: "tool-result",
+		result
+	}),
+	queue: {
+		remove: (options) => commandInput({
+			action: "remove",
+			...options
+		}),
+		sendNow: (options) => commandInput({
+			action: "send-now",
+			...options
+		}),
+		edit: (options) => commandInput({
+			action: "edit",
+			...options
+		}),
+		move: (options) => commandInput({
+			action: "move",
+			...options
+		})
+	},
+	stop: (options) => commandInput({
+		action: "stop",
+		...options
+	}),
+	steer: (options) => commandInput({
+		action: "steer",
+		...options
+	}),
+	pause: (options) => commandInput({
+		action: "pause",
+		...options
+	}),
+	resume: () => commandInput({ action: "resume" }),
 	message(message, options) {
 		return messageInput(message, options?.generate);
 	},
 	seed(message) {
 		return messageInput(message, false);
 	},
-	approval(response) {
-		return [{
-			type: "ai.approval.responded",
-			id: `ai.approval:${encodeURIComponent(response.messageId)}:${encodeURIComponent(response.generationId)}:${encodeURIComponent(response.approvalId)}:response`,
-			payload: response
-		}];
-	},
-	input(response) {
-		return [{
-			type: "ai.input.responded",
-			id: `ai.input:${encodeURIComponent(response.messageId)}:${encodeURIComponent(response.generationId)}:${encodeURIComponent(response.inputId)}:response`,
-			payload: response
-		}];
-	},
-	requestInput(request) {
-		return [{
-			type: "ai.input.requested",
-			id: `ai.input:${encodeURIComponent(request.messageId)}:${encodeURIComponent(request.generationId)}:${encodeURIComponent(request.inputId)}:request`,
-			payload: request
-		}];
-	},
-	retry(retryOptions) {
-		return [{
-			type: "ai.retry.requested",
-			id: `ai.retry:${retryOptions.retryId}`,
-			payload: retryOptions
-		}];
-	},
-	interrupt(interruption) {
-		return [{
-			type: "ai.message.interrupted",
-			id: `ai.interrupt:${interruption.generationId ?? interruption.requestId}`,
-			payload: interruption
-		}];
-	}
+	approval: (response) => [{
+		...commandInput({
+			action: "approval",
+			response
+		})[0],
+		id: `ai.approval:${encodeURIComponent(response.messageId)}:${encodeURIComponent(response.generationId)}:${encodeURIComponent(response.approvalId)}:response`
+	}],
+	input: (response) => [{
+		...commandInput({
+			action: "input",
+			response
+		})[0],
+		id: `ai.input:${encodeURIComponent(response.messageId)}:${encodeURIComponent(response.generationId)}:${encodeURIComponent(response.inputId)}:response`
+	}],
+	requestInput: (request) => [{
+		...commandInput({
+			action: "request-input",
+			request
+		})[0],
+		id: `ai.input:${encodeURIComponent(request.messageId)}:${encodeURIComponent(request.generationId)}:${encodeURIComponent(request.inputId)}:request`
+	}],
+	retry: (request) => [{
+		...commandInput({
+			action: "retry",
+			request
+		})[0],
+		id: `ai.retry:${request.retryId}`
+	}],
+	interrupt: (request) => [{
+		...commandInput({
+			action: "interrupt",
+			request
+		})[0],
+		id: `ai.interrupt:${request.generationId ?? request.requestId}`
+	}]
 };
 /**
 * Read the durable handler context ambient to the current AI tool
@@ -1267,10 +1985,13 @@ function agent(options) {
 	});
 	return {
 		contract: agentContract,
-		reducer: agentContract.reducer({
-			name: options.reducerName ?? "a2.ai.state.v10",
-			initialState: initialState()
-		}).fold((state, event) => reduceAIState(state, event))
+		reducer: {
+			...agentContract.reducer({
+				name: options.reducerName ?? "a2.ai.state.v17",
+				initialState: initialState()
+			}).fold((state, event) => reduceAIState(state, event)),
+			[clientStateProjection]: projectAIClientState
+		}
 	};
 }
 //#endregion