experimental-a2 0.17.0 → 0.18.0

package/dist/ai-fx.js

@@ -0,0 +1,634 @@
+import { t as boundedCache } from "./bounded-cache-CPHWF-8h.js";
+import { c as pending, d as saveHarness, i as gatewayCredential, l as readHarness, n as deferred, r as defineHarness, t as Divergence } from "./ai-harness-BuLh_EYi.js";
+import { asSchema } from "ai";
+//#region src/ai-fx.ts
+/**
+* experimental-a2/ai/fx — `fx()`: the FX harness for `agent({ harness })`.
+* Server-only; FX's kernel comes from the optional `libfx` peer dependency.
+*/
+/**
+* The FX harness. Every model call FX makes is one durable step; A2 rebuilds
+* the kernel for each step from its latest checkpoint and the log since.
+*/
+function fx() {
+	return defineHarness("fx", {
+		tools: {},
+		step: runStep
+	});
+}
+const SNAPSHOT_VERSION = 1;
+const CATALOG_TTL_MS = 36e5;
+function fail(state, error) {
+	state.failure ??= error;
+	state.fxTurn.cancel();
+	throw state.failure;
+}
+const diverged = (message) => new Divergence("FX", message);
+async function runStep(step) {
+	const { createFxAgent } = await loadLibfx();
+	const credential = gatewayCredential("fx");
+	const name = `${step.agentName}.a2.harness.fx`;
+	const { replayAll, ...first } = await readHarness({
+		step,
+		name,
+		parse: savedCheckpoint
+	});
+	let read = first;
+	let completion = {};
+	let stopped = false;
+	let agent;
+	let turn;
+	const run = async (controller, turns) => {
+		controller.enqueue({
+			type: "start",
+			messageId: step.responseMessageId
+		});
+		for (const plan of turns) {
+			if (stopped) return;
+			const fxTurn = agent.prompt(plan.prompt, { signal: step.signal });
+			const state = {
+				plan,
+				fxTurn,
+				next: 0,
+				served: [],
+				answered: /* @__PURE__ */ new Set(),
+				live: false,
+				liveStep: false,
+				toolsRequested: deferred()
+			};
+			turn = state;
+			const drained = (async () => {
+				for await (const _ of fxTurn);
+			})();
+			drained.catch(() => {});
+			if (plan.end !== "live") {
+				const result = await fxTurn.result.catch((error) => {
+					throw state.failure ?? error;
+				});
+				await drained;
+				if (state.failure) throw state.failure;
+				const expected = plan.end === "stop" ? "end_turn" : "cancelled";
+				if (result.stopReason !== expected) throw diverged(`a recorded turn ended with ${result.stopReason}, not ${expected}`);
+				continue;
+			}
+			const outcome = await Promise.race([fxTurn.result.then((result) => ({
+				ended: true,
+				result
+			})), state.toolsRequested.promise.then(() => ({ ended: false }))]).catch((error) => {
+				throw state.failure ?? error;
+			});
+			if (state.failure) throw state.failure;
+			await state.parsed;
+			if (outcome.ended) {
+				await drained;
+				if (outcome.result.stopReason === "end_turn" && !step.signal.aborted) await saveCheckpoint();
+			} else fxTurn.cancel();
+			controller.enqueue({ type: "finish-step" });
+			controller.enqueue({
+				type: "finish",
+				...completion.finishReason === void 0 ? {} : { finishReason: completion.finishReason }
+			});
+		}
+	};
+	const saveCheckpoint = async () => {
+		let checkpoint;
+		try {
+			checkpoint = await agent.checkpoint();
+		} catch {
+			return;
+		}
+		await saveHarness({
+			step,
+			name,
+			state: {
+				version: SNAPSHOT_VERSION,
+				checkpoint: Buffer.from(checkpoint).toString("base64")
+			}
+		});
+	};
+	const hostFetch = async (input, init = {}) => {
+		const url = input instanceof Request ? input.url : String(input);
+		if ((init.method ?? "GET").toUpperCase() === "GET") return catalog(url, credential, withAuth(init.headers, credential));
+		const state = turn;
+		if (state.failure) throw state.failure;
+		const compaction = isCompaction(decodeBody(init.body));
+		const recorded = state.plan.calls[state.next];
+		if (recorded !== void 0) {
+			if (recorded.kind === "compaction" !== compaction) fail(state, diverged(`request ${state.next} is not a ${recorded.kind}`));
+			const index = state.next++;
+			if (recorded.kind === "step") {
+				state.served = recorded.toolCalls;
+				state.answered = /* @__PURE__ */ new Set();
+			}
+			const steers = state.plan.steers.get(index) ?? [];
+			return relay(recorded.sse, async () => {
+				for (const text of steers) await state.fxTurn.steer(text);
+			});
+		}
+		if (state.plan.end === "stop") fail(state, diverged("FX continued a turn the log ended"));
+		if (state.plan.end === "interrupted") {
+			state.fxTurn.cancel();
+			throw new DOMException("The recorded turn was interrupted", "AbortError");
+		}
+		if (state.liveStep && !compaction) {
+			state.toolsRequested.resolve();
+			return pending(init.signal);
+		}
+		state.live = true;
+		return live(state, url, init, compaction);
+	};
+	let compactions = 0;
+	const live = async (state, url, init, compaction) => {
+		const response = await fetch(url, {
+			...init,
+			headers: withAuth(init.headers, credential)
+		});
+		if (!response.ok || response.body === null) return response;
+		const [forKernel, forLog] = response.body.tee();
+		const previous = state.parsed;
+		if (compaction) {
+			const id = `fx-compaction:${step.requestIndex}:${compactions++}`;
+			state.parsed = (async () => {
+				const all = await readParts(forLog);
+				await previous;
+				emit({
+					type: "data-a2-compaction",
+					id,
+					data: compactionData(all)
+				});
+			})();
+		} else {
+			state.liveStep = true;
+			state.parsed = (async () => {
+				await previous;
+				emit({ type: "start-step" });
+				await streamStep(forLog, emit, (finished) => {
+					completion = finished;
+				});
+			})();
+		}
+		state.parsed.catch(() => {});
+		return new Response(forKernel, {
+			status: response.status,
+			headers: response.headers
+		});
+	};
+	const hostTools = await kernelTools(step.tools, (toolName, toolInput) => {
+		const state = turn;
+		if (state.failure) throw state.failure;
+		const call = state.served.find((candidate) => candidate.toolName === toolName && !state.answered.has(candidate.toolCallId) && sameJson(candidate.input, toolInput));
+		const result = call === void 0 ? void 0 : results.get(call.toolCallId);
+		if (call !== void 0 && result !== void 0) {
+			state.answered.add(call.toolCallId);
+			if (result.error !== void 0) throw new Error(result.error);
+			if (result.denied === true) throw new Error("The tool call was denied.");
+			return result.output ?? null;
+		}
+		if (state.live) {
+			state.toolsRequested.resolve();
+			return pending(void 0);
+		}
+		if (state.plan.end === "interrupted") {
+			state.fxTurn.cancel();
+			return pending(void 0);
+		}
+		return fail(state, diverged(`no recorded result for ${toolName}`));
+	});
+	let turns = read.turns.map(turnPlan);
+	let results = read.results;
+	let controller;
+	let closed = false;
+	const emit = (chunk) => {
+		if (!closed) controller.enqueue(chunk);
+	};
+	const create = (checkpoint) => createFxAgent({
+		apiKey: credential.token,
+		model: kernelModel(step),
+		...step.instructions.length === 0 ? {} : { instructions: step.instructions },
+		tools: hostTools,
+		...checkpoint === void 0 ? {} : { checkpoint },
+		fetch: hostFetch
+	});
+	return {
+		stream: new ReadableStream({
+			start(streamController) {
+				controller = streamController;
+				const abort = () => {
+					stopped = true;
+					turn?.fxTurn.cancel();
+				};
+				step.signal.addEventListener("abort", abort, { once: true });
+				(async () => {
+					try {
+						try {
+							agent = await create(read.saved);
+						} catch (error) {
+							if (read.saved === void 0) throw error;
+							read = await replayAll();
+							turns = read.turns.map(turnPlan);
+							results = read.results;
+							agent = await create(void 0);
+						}
+						await run(streamController, turns);
+						closed = true;
+						streamController.close();
+					} catch (error) {
+						closed = true;
+						streamController.error(step.signal.aborted ? step.signal.reason : error);
+					} finally {
+						step.signal.removeEventListener("abort", abort);
+						await agent?.close().catch(() => {});
+					}
+				})();
+			},
+			cancel() {
+				closed = true;
+				stopped = true;
+				turn?.fxTurn.cancel();
+			}
+		}),
+		completion: () => completion
+	};
+}
+function turnPlan(turn) {
+	const calls = [];
+	const steers = /* @__PURE__ */ new Map();
+	const steer = (at, texts) => {
+		if (texts !== void 0) steers.set(Math.max(0, at), texts);
+	};
+	steer(0, turn.generations.length === 0 ? turn.steers.get(0) : void 0);
+	turn.generations.forEach((generation, index) => {
+		calls.push(...recordedCalls(generation.chunks, generation.completed));
+		steer(calls.length - 1, turn.steers.get(index));
+	});
+	return {
+		prompt: turn.prompt,
+		calls,
+		steers,
+		end: turn.end
+	};
+}
+/** A completed generation's model calls: its compactions, then its step. */
+function recordedCalls(chunks, completed) {
+	const calls = [];
+	const parts = [];
+	const toolCalls = [];
+	const inputText = /* @__PURE__ */ new Map();
+	for (const chunk of chunks) {
+		const metadata = "providerMetadata" in chunk && chunk.providerMetadata !== void 0 ? { providerMetadata: chunk.providerMetadata } : {};
+		switch (chunk.type) {
+			case "data-a2-compaction":
+				calls.push({
+					kind: "compaction",
+					sse: compactionSse(chunk.data),
+					toolCalls: []
+				});
+				break;
+			case "text-start":
+			case "text-end":
+			case "reasoning-start":
+			case "reasoning-end":
+				parts.push({
+					type: chunk.type,
+					id: chunk.id,
+					...metadata
+				});
+				break;
+			case "text-delta":
+			case "reasoning-delta":
+				parts.push({
+					type: chunk.type,
+					id: chunk.id,
+					delta: chunk.delta,
+					...metadata
+				});
+				break;
+			case "tool-input-start":
+				inputText.set(chunk.toolCallId, "");
+				parts.push({
+					type: "tool-input-start",
+					id: chunk.toolCallId,
+					toolName: chunk.toolName,
+					...metadata
+				});
+				break;
+			case "tool-input-delta":
+				inputText.set(chunk.toolCallId, (inputText.get(chunk.toolCallId) ?? "") + chunk.inputTextDelta);
+				parts.push({
+					type: "tool-input-delta",
+					id: chunk.toolCallId,
+					delta: chunk.inputTextDelta
+				});
+				break;
+			case "tool-input-error":
+				if (inputText.has(chunk.toolCallId)) parts.push({
+					type: "tool-input-end",
+					id: chunk.toolCallId
+				});
+				parts.push({
+					type: "tool-call",
+					toolCallId: chunk.toolCallId,
+					toolName: chunk.toolName,
+					input: inputText.get(chunk.toolCallId) || (typeof chunk.input === "string" ? chunk.input : JSON.stringify(chunk.input))
+				});
+				break;
+			case "tool-input-available":
+				if (inputText.has(chunk.toolCallId)) parts.push({
+					type: "tool-input-end",
+					id: chunk.toolCallId
+				});
+				toolCalls.push({
+					toolCallId: chunk.toolCallId,
+					toolName: chunk.toolName,
+					input: chunk.input
+				});
+				parts.push({
+					type: "tool-call",
+					toolCallId: chunk.toolCallId,
+					toolName: chunk.toolName,
+					input: inputText.get(chunk.toolCallId) || JSON.stringify(chunk.input),
+					...metadata
+				});
+		}
+	}
+	parts.push({
+		type: "finish",
+		finishReason: { unified: completed.finishReason ?? "other" },
+		usage: streamUsage(completed.usage)
+	});
+	calls.push({
+		kind: "step",
+		sse: sse(parts),
+		toolCalls
+	});
+	return calls;
+}
+function compactionSse(data) {
+	return sse([
+		{
+			type: "text-start",
+			id: "0"
+		},
+		{
+			type: "text-delta",
+			id: "0",
+			delta: data.summary ?? ""
+		},
+		{
+			type: "text-end",
+			id: "0"
+		},
+		{
+			type: "finish",
+			finishReason: { unified: "stop" },
+			usage: streamUsage(data.usage)
+		}
+	]);
+}
+/** Streams one live step response as UI chunks and reports its finish. */
+async function streamStep(body, emit, finished) {
+	for await (const part of sseParts(body)) {
+		const metadata = part["providerMetadata"] === void 0 ? {} : { providerMetadata: part["providerMetadata"] };
+		switch (part.type) {
+			case "text-start":
+			case "text-end":
+			case "reasoning-start":
+			case "reasoning-end":
+				emit({
+					type: part.type,
+					id: part["id"],
+					...metadata
+				});
+				break;
+			case "text-delta":
+			case "reasoning-delta":
+				emit({
+					type: part.type,
+					id: part["id"],
+					delta: part["delta"],
+					...metadata
+				});
+				break;
+			case "tool-input-start":
+				emit({
+					type: "tool-input-start",
+					toolCallId: part["id"],
+					toolName: part["toolName"],
+					...metadata
+				});
+				break;
+			case "tool-input-delta":
+				emit({
+					type: "tool-input-delta",
+					toolCallId: part["id"],
+					inputTextDelta: part["delta"]
+				});
+				break;
+			case "tool-call": {
+				const text = part["input"];
+				let input;
+				try {
+					input = JSON.parse(text);
+				} catch (error) {
+					emit({
+						type: "tool-input-error",
+						toolCallId: part["toolCallId"],
+						toolName: part["toolName"],
+						input: text,
+						errorText: error instanceof Error ? error.message : String(error)
+					});
+					break;
+				}
+				emit({
+					type: "tool-input-available",
+					toolCallId: part["toolCallId"],
+					toolName: part["toolName"],
+					input,
+					...metadata
+				});
+				break;
+			}
+			case "finish": {
+				const reason = part["finishReason"];
+				finished({
+					...reason?.unified === void 0 ? {} : { finishReason: reason.unified },
+					usage: modelUsage(part["usage"])
+				});
+				break;
+			}
+			case "error": emit({
+				type: "error",
+				errorText: errorText(part["error"])
+			});
+		}
+	}
+}
+async function readParts(body) {
+	const all = [];
+	for await (const part of sseParts(body)) all.push(part);
+	return all;
+}
+function compactionData(all) {
+	const finish = all.find((part) => part.type === "finish");
+	return {
+		status: "completed",
+		summary: all.filter((part) => part.type === "text-delta").map((part) => part["delta"]).join(""),
+		...finish === void 0 ? {} : { usage: modelUsage(finish["usage"]) }
+	};
+}
+async function* sseParts(body) {
+	const decoder = new TextDecoder();
+	let pendingText = "";
+	for await (const chunk of body) {
+		pendingText += decoder.decode(chunk, { stream: true });
+		let end;
+		while ((end = pendingText.indexOf("\n\n")) !== -1) {
+			const frame = pendingText.slice(0, end);
+			pendingText = pendingText.slice(end + 2);
+			if (frame.startsWith("data: {")) yield JSON.parse(frame.slice(6));
+		}
+	}
+}
+/**
+* Hands a recorded response to the kernel frame by frame. Steering due after
+* it is queued before its finish part, while the kernel still waits on it.
+*/
+function relay(text, beforeFinish) {
+	const encoder = new TextEncoder();
+	const frames = text.split(/(?<=\n\n)/);
+	let index = 0;
+	let steered = false;
+	return new Response(new ReadableStream({ async pull(controller) {
+		const frame = frames[index++];
+		if (frame === void 0) {
+			controller.close();
+			return;
+		}
+		if (!steered && frame.includes("\"type\":\"finish\"")) {
+			steered = true;
+			await beforeFinish();
+		}
+		controller.enqueue(encoder.encode(frame));
+	} }), { headers: { "content-type": "text/event-stream" } });
+}
+async function loadLibfx() {
+	try {
+		return await import("libfx");
+	} catch (error) {
+		throw new Error("fx() needs the libfx package: install libfx", { cause: error });
+	}
+}
+function withAuth(headers, credential) {
+	const result = new Headers(headers);
+	result.set("ai-gateway-auth-method", credential.method);
+	return result;
+}
+function kernelModel(step) {
+	const effort = step.reasoning === void 0 || step.reasoning === "provider-default" ? void 0 : step.reasoning;
+	const fast = step.speed === "fast";
+	if (effort === void 0 && !fast) return step.model;
+	return {
+		id: step.model,
+		...effort === void 0 ? {} : { effort },
+		...fast ? { fast } : {}
+	};
+}
+async function kernelTools(tools, execute) {
+	return Promise.all(Object.entries(tools).filter(([, tool]) => tool.type !== "provider").map(async ([toolName, tool]) => ({
+		name: toolName,
+		description: typeof tool.description === "string" ? tool.description : toolName,
+		inputSchema: await asSchema(tool.inputSchema).jsonSchema,
+		execute: (input) => execute(toolName, input)
+	})));
+}
+const catalogCache = boundedCache({
+	maxEntries: 16,
+	maxBytes: 16
+});
+/**
+* Model catalog reads, shared for an hour by every step in the process that
+* uses the same credential; credentials can see different catalogs.
+*/
+async function catalog(url, credential, headers) {
+	const key = `${url}\n${credential.token}`;
+	const now = Date.now();
+	let entry = catalogCache.get(key);
+	if (entry === void 0 || entry.expires <= now) {
+		const body = fetch(url, { headers }).then(async (response) => {
+			if (!response.ok) throw new Error(`catalog request failed: ${response.status}`);
+			return response.text();
+		});
+		entry = {
+			expires: now + CATALOG_TTL_MS,
+			body
+		};
+		catalogCache.set(key, entry, 1);
+		body.catch(() => catalogCache.delete(key));
+	}
+	return new Response(await entry.body, { headers: { "content-type": "application/json" } });
+}
+function savedCheckpoint(state) {
+	if (typeof state !== "object" || state === null) return void 0;
+	const { version, checkpoint } = state;
+	if (version !== SNAPSHOT_VERSION || typeof checkpoint !== "string") return void 0;
+	return new Uint8Array(Buffer.from(checkpoint, "base64"));
+}
+function isCompaction(body) {
+	return JSON.parse(body).toolChoice?.type === "none";
+}
+function decodeBody(body) {
+	if (typeof body === "string") return body;
+	if (body instanceof Uint8Array || body instanceof ArrayBuffer) return new TextDecoder().decode(body);
+	throw new TypeError("FX sent an unexpected request body");
+}
+function sameJson(a, b) {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+function sse(all) {
+	return all.map((part) => `data: ${JSON.stringify(part)}\n\n`).join("") + "data: [DONE]\n\n";
+}
+function errorText(error) {
+	if (typeof error === "string") return error;
+	if (error instanceof Error) return error.message;
+	return JSON.stringify(error);
+}
+/** A Gateway stream usage, as AI SDK normalizes it. */
+function modelUsage(value) {
+	const usage = value ?? {};
+	const input = usage.inputTokens ?? {};
+	const output = usage.outputTokens ?? {};
+	return {
+		inputTokens: input.total,
+		inputTokenDetails: {
+			noCacheTokens: input.noCache,
+			cacheReadTokens: input.cacheRead,
+			cacheWriteTokens: input.cacheWrite
+		},
+		outputTokens: output.total,
+		outputTokenDetails: {
+			textTokens: output.text,
+			reasoningTokens: output.reasoning
+		},
+		totalTokens: input.total === void 0 && output.total === void 0 ? void 0 : (input.total ?? 0) + (output.total ?? 0)
+	};
+}
+/** The inverse of `modelUsage`, for replay. */
+function streamUsage(usage) {
+	return {
+		inputTokens: {
+			total: usage?.inputTokens,
+			noCache: usage?.inputTokenDetails?.noCacheTokens,
+			cacheRead: usage?.inputTokenDetails?.cacheReadTokens,
+			cacheWrite: usage?.inputTokenDetails?.cacheWriteTokens
+		},
+		outputTokens: {
+			total: usage?.outputTokens,
+			text: usage?.outputTokenDetails?.textTokens,
+			reasoning: usage?.outputTokenDetails?.reasoningTokens
+		}
+	};
+}
+//#endregion
+export { fx };
+
+//# sourceMappingURL=ai-fx.js.map