@copilotkit/runtime 1.81.0 → 1.83.0

package/dist/agent/url-download.d.cts

@@ -0,0 +1,80 @@
+
+import { Experimental_DownloadFunction } from "ai";
+
+//#region src/agent/url-download.d.ts
+/** Options for the default, public-network-only URL downloader. */
+interface SafeUrlDownloadOptions {
+  /**
+   * Hostnames that may be downloaded. When omitted, any hostname is allowed.
+   * Every resolved address must be public in both cases, and every redirect
+   * target must match as well.
+   *
+   * - `cdn.example.com` matches exactly that host.
+   * - `*.example.com` matches any subdomain (`a.example.com`,
+   *   `a.b.example.com`) but not `example.com` itself; list both if needed.
+   *
+   * Matching ignores case and a trailing dot. Unicode names match their
+   * punycode form, and an IPv6 address may be given with or without
+   * brackets. An entry with a scheme, port, path or user, and a wildcard over
+   * an IP address (`*.1.2.3.4`), are rejected when the downloader is created.
+   * An empty list refuses every server-side download; `data:` URLs and URLs
+   * that the model takes directly are not downloaded, so they still pass.
+   */
+  allowedHosts?: string[];
+  /** Largest response body to accept, in bytes (at least 1). Default: 20 MiB. */
+  maxBytes?: number;
+  /**
+   * Time limit for one download, including redirects, in ms. From 1 to
+   * 2147483647 (the largest delay `setTimeout` supports). Default: 30000.
+   */
+  timeoutMs?: number;
+  /** Largest number of redirects to follow; 0 follows none. Default: 3. */
+  maxRedirects?: number;
+  /**
+   * Largest number of distinct URLs to download for one model call (at
+   * least 1); a URL that appears twice is downloaded once. The AI SDK
+   * downloads the attachments of every user message again for each step of
+   * a multi-step run. Default: 20.
+   */
+  maxDownloads?: number;
+  /**
+   * Largest number of bytes to download for one model call, over all its
+   * URLs (at least 1). Default: 50 MiB.
+   */
+  maxTotalBytes?: number;
+}
+/** Options for {@link createSafeUrlDownload}. */
+interface CreateSafeUrlDownloadOptions extends SafeUrlDownloadOptions {
+  /**
+   * Stops every download of this function when it aborts, for example the
+   * run's `ctx.abortSignal` in BuiltInAgent's factory mode. Without it, a
+   * download that is running when the run is aborted goes on until it ends
+   * or reaches `timeoutMs`.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Creates an AI SDK download function (`experimental_download`) that only
+ * fetches public internet addresses, with the same checks and limits as
+ * BuiltInAgent's default downloader. Pass it to `streamText` yourself when
+ * you use BuiltInAgent's AI SDK factory mode. Create it in the factory with
+ * the run's abort signal, so that an aborted run stops its downloads:
+ *
+ * ```ts
+ * import { createSafeUrlDownload } from "@copilotkit/runtime/v2";
+ *
+ * factory: (ctx) =>
+ *   streamText({
+ *     model,
+ *     messages,
+ *     abortSignal: ctx.abortSignal,
+ *     experimental_download: createSafeUrlDownload({ signal: ctx.abortSignal }),
+ *   }),
+ * ```
+ *
+ * Invalid options throw here, when the function is created.
+ */
+declare function createSafeUrlDownload(options?: CreateSafeUrlDownloadOptions): Experimental_DownloadFunction;
+//#endregion
+export { CreateSafeUrlDownloadOptions, SafeUrlDownloadOptions, createSafeUrlDownload };
+//# sourceMappingURL=url-download.d.cts.map

package/dist/agent/url-download.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-download.d.cts","names":[],"sources":["../../src/agent/url-download.ts"],"mappings":";;;;;UAwCiB,sBAAA;EAAsB;;;;;;;;;;;AA42BvC;;;;;EA31BE,YAAA;EAk2BS;EAh2BT,QAAA;EAg2BoB;AAwBtB;;;EAn3BE,SAAA;EAo3BS;EAl3BT,YAAA;EAm3BC;;;;;;EA52BD,YAAA;;;;;EAKA,aAAA;AAAA;;UAs0Be,4BAAA,SAAqC,sBAAA;;;;;;;EAOpD,MAAA,GAAS,WAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;iBAwBK,qBAAA,CACd,OAAA,GAAS,4BAAA,GACR,6BAAA"}

package/dist/agent/url-download.d.mts

@@ -0,0 +1,80 @@
+
+import { Experimental_DownloadFunction } from "ai";
+
+//#region src/agent/url-download.d.ts
+/** Options for the default, public-network-only URL downloader. */
+interface SafeUrlDownloadOptions {
+  /**
+   * Hostnames that may be downloaded. When omitted, any hostname is allowed.
+   * Every resolved address must be public in both cases, and every redirect
+   * target must match as well.
+   *
+   * - `cdn.example.com` matches exactly that host.
+   * - `*.example.com` matches any subdomain (`a.example.com`,
+   *   `a.b.example.com`) but not `example.com` itself; list both if needed.
+   *
+   * Matching ignores case and a trailing dot. Unicode names match their
+   * punycode form, and an IPv6 address may be given with or without
+   * brackets. An entry with a scheme, port, path or user, and a wildcard over
+   * an IP address (`*.1.2.3.4`), are rejected when the downloader is created.
+   * An empty list refuses every server-side download; `data:` URLs and URLs
+   * that the model takes directly are not downloaded, so they still pass.
+   */
+  allowedHosts?: string[];
+  /** Largest response body to accept, in bytes (at least 1). Default: 20 MiB. */
+  maxBytes?: number;
+  /**
+   * Time limit for one download, including redirects, in ms. From 1 to
+   * 2147483647 (the largest delay `setTimeout` supports). Default: 30000.
+   */
+  timeoutMs?: number;
+  /** Largest number of redirects to follow; 0 follows none. Default: 3. */
+  maxRedirects?: number;
+  /**
+   * Largest number of distinct URLs to download for one model call (at
+   * least 1); a URL that appears twice is downloaded once. The AI SDK
+   * downloads the attachments of every user message again for each step of
+   * a multi-step run. Default: 20.
+   */
+  maxDownloads?: number;
+  /**
+   * Largest number of bytes to download for one model call, over all its
+   * URLs (at least 1). Default: 50 MiB.
+   */
+  maxTotalBytes?: number;
+}
+/** Options for {@link createSafeUrlDownload}. */
+interface CreateSafeUrlDownloadOptions extends SafeUrlDownloadOptions {
+  /**
+   * Stops every download of this function when it aborts, for example the
+   * run's `ctx.abortSignal` in BuiltInAgent's factory mode. Without it, a
+   * download that is running when the run is aborted goes on until it ends
+   * or reaches `timeoutMs`.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Creates an AI SDK download function (`experimental_download`) that only
+ * fetches public internet addresses, with the same checks and limits as
+ * BuiltInAgent's default downloader. Pass it to `streamText` yourself when
+ * you use BuiltInAgent's AI SDK factory mode. Create it in the factory with
+ * the run's abort signal, so that an aborted run stops its downloads:
+ *
+ * ```ts
+ * import { createSafeUrlDownload } from "@copilotkit/runtime/v2";
+ *
+ * factory: (ctx) =>
+ *   streamText({
+ *     model,
+ *     messages,
+ *     abortSignal: ctx.abortSignal,
+ *     experimental_download: createSafeUrlDownload({ signal: ctx.abortSignal }),
+ *   }),
+ * ```
+ *
+ * Invalid options throw here, when the function is created.
+ */
+declare function createSafeUrlDownload(options?: CreateSafeUrlDownloadOptions): Experimental_DownloadFunction;
+//#endregion
+export { CreateSafeUrlDownloadOptions, SafeUrlDownloadOptions, createSafeUrlDownload };
+//# sourceMappingURL=url-download.d.mts.map

package/dist/agent/url-download.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-download.d.mts","names":[],"sources":["../../src/agent/url-download.ts"],"mappings":";;;;;UAwCiB,sBAAA;EAAsB;;;;;;;;;;;AA42BvC;;;;;EA31BE,YAAA;EAk2BS;EAh2BT,QAAA;EAg2BoB;AAwBtB;;;EAn3BE,SAAA;EAo3BS;EAl3BT,YAAA;EAm3BC;;;;;;EA52BD,YAAA;;;;;EAKA,aAAA;AAAA;;UAs0Be,4BAAA,SAAqC,sBAAA;;;;;;;EAOpD,MAAA,GAAS,WAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;iBAwBK,qBAAA,CACd,OAAA,GAAS,4BAAA,GACR,6BAAA"}

package/dist/agent/url-download.mjs

@@ -0,0 +1,501 @@
+import "reflect-metadata";
+import { COPILOTKIT_VERSION } from "@copilotkit/shared";
+import { DownloadError } from "ai";
+
+//#region src/agent/url-download.ts
+const DEFAULT_MAX_BYTES = 20 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 3e4;
+const DEFAULT_MAX_REDIRECTS = 3;
+const DEFAULT_MAX_DOWNLOADS = 20;
+const DEFAULT_MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+const HOST_REFUSED = "The URL host is not a public address, or it could not be resolved.";
+const DOWNLOAD_FAILED = "The download failed.";
+const USER_AGENT = `CopilotKit-Runtime/${COPILOTKIT_VERSION}`;
+const REDIRECT_STATUSES = new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+let nodeModules;
+function loadNodeModules() {
+	nodeModules ??= Promise.all([
+		import("node:dns/promises"),
+		import("node:http"),
+		import("node:https"),
+		import("node:net")
+	]).then(([dns, http, https, net]) => ({
+		dns,
+		http,
+		https,
+		net
+	})).catch((error) => {
+		nodeModules = void 0;
+		throw error;
+	});
+	return nodeModules;
+}
+let defaultPolicy;
+function buildAddressPolicy(net) {
+	const nonPublicV4 = new net.BlockList();
+	for (const [address, prefix] of [
+		["0.0.0.0", 8],
+		["10.0.0.0", 8],
+		["100.64.0.0", 10],
+		["127.0.0.0", 8],
+		["169.254.0.0", 16],
+		["172.16.0.0", 12],
+		["192.0.0.0", 24],
+		["192.0.2.0", 24],
+		["192.88.99.0", 24],
+		["192.168.0.0", 16],
+		["198.18.0.0", 15],
+		["198.51.100.0", 24],
+		["203.0.113.0", 24],
+		["224.0.0.0", 4],
+		["240.0.0.0", 4]
+	]) nonPublicV4.addSubnet(address, prefix, "ipv4");
+	const globalV6 = new net.BlockList();
+	globalV6.addSubnet("2000::", 3, "ipv6");
+	const nonPublicV6 = new net.BlockList();
+	for (const [address, prefix] of [
+		["2001::", 23],
+		["2001:db8::", 32],
+		["2002::", 16],
+		["3fff::", 20]
+	]) nonPublicV6.addSubnet(address, prefix, "ipv6");
+	return (address) => {
+		const family = net.isIP(address);
+		if (family === 4) return !nonPublicV4.check(address, "ipv4");
+		if (family !== 6 || address.includes("%")) return false;
+		return globalV6.check(address, "ipv6") && !nonPublicV6.check(address, "ipv6");
+	};
+}
+/**
+* True when the server must not fetch this URL itself and returns `null` so
+* the AI SDK handles it: the provider takes the URL as-is, or it is a `data:`
+* URL, which the AI SDK decodes locally without any network request.
+*/
+function leftToAiSdk({ url, isUrlSupportedByModel }) {
+	return isUrlSupportedByModel || url.protocol === "data:";
+}
+/** The URL without its query and fragment, which can hold credentials. */
+function urlForLog(url) {
+	try {
+		const parsed = new URL(String(url));
+		return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+	} catch {
+		return "(invalid URL)";
+	}
+}
+/** `text` with the query and fragment removed from every URL in it. */
+function redactUrls(text) {
+	return text.replace(/\b([a-z][a-z0-9+.-]*:\/\/[^\s?#"'`<>]*)[?#][^\s"'`<>]*/gi, "$1");
+}
+const loggedErrors = /* @__PURE__ */ new WeakSet();
+/**
+* Returns the error for a failed or refused download and logs it on the
+* server. `detail` goes only to the log: the client sees `message`, which
+* never holds the URL's query, a resolved address or a raw network error.
+* For a refused host, `message` is the same whether the name did not resolve
+* or resolved to a non-public address, so that it does not reveal internal
+* DNS names.
+*/
+function refuse(url, message, detail, statusCode) {
+	console.warn(redactUrls(`[BuiltInAgent] URL download failed for ${urlForLog(url)}: ${message}${detail ? ` (${detail})` : ""}`));
+	const error = new DownloadError({
+		url: urlForLog(url),
+		message,
+		statusCode
+	});
+	loggedErrors.add(error);
+	return error;
+}
+/**
+* @internal BuiltInAgent's `onError` for its `streamText` call. The AI SDK's
+* default handler prints the whole error, which for a download error holds
+* the URL with its query. This logs an error once, with the same detail
+* (for a provider API error, its status code and response body) but with the
+* query and fragment removed from every URL, and skips the download errors
+* that were already logged here.
+*/
+function logModelCallError(error) {
+	if (typeof error === "object" && error !== null && loggedErrors.has(error)) return;
+	const frames = error instanceof Error && error.stack ? error.stack.split("\n").filter((line) => /^\s+at /.test(line)).join("\n") : "";
+	console.error(redactUrls(`[BuiltInAgent] The model call failed: ${describeModelError(error)}${frames ? `\n${frames}` : ""}`));
+}
+const MAX_LOGGED_FIELD_LENGTH = 2e3;
+function truncateForLog(text) {
+	return text.length > MAX_LOGGED_FIELD_LENGTH ? `${text.slice(0, MAX_LOGGED_FIELD_LENGTH)}… (${text.length} characters)` : text;
+}
+/**
+* {@link describeError}, followed by the other fields of the error, such as
+* the `statusCode`, `responseBody` and `url` of the AI SDK's APICallError. A
+* value that is not an Error, such as the plain object that a provider
+* stream sends as its error, is logged as JSON.
+*/
+function describeModelError(error) {
+	if (!(error instanceof Error)) return truncateForLog(describeValue(error));
+	const fields = Object.entries(error).filter(([key]) => ![
+		"name",
+		"message",
+		"stack",
+		"cause",
+		"code"
+	].includes(key)).map(([key, value]) => {
+		return `${key}: ${truncateForLog(value instanceof Error ? describeError(value) : typeof value === "string" ? value : describeValue(value))}`;
+	});
+	return `${error.name && error.name !== "Error" ? `${error.name}: ` : ""}${describeError(error)}${fields.length > 0 ? ` {${fields.join("; ")}}` : ""}`;
+}
+/** Message, error code and causes of an error, for the server log. */
+function describeError(error, depth = 0) {
+	if (typeof error === "string") return error;
+	if (!(error instanceof Error)) return truncateForLog(describeValue(error));
+	const code = error.code;
+	const text = typeof code === "string" && !error.message.includes(code) ? `${code}: ${error.message}` : error.message;
+	return error.cause !== void 0 && depth < 3 ? `${text}; caused by ${describeError(error.cause, depth + 1)}` : text;
+}
+/**
+* A printable form of a configuration value for an error message. Unlike
+* `JSON.stringify`, it never throws (BigInt) and never gives `undefined`
+* (Symbol, function).
+*/
+function describeValue(value) {
+	if (typeof value === "bigint") return `${value}n`;
+	if (typeof value === "function") return "a function";
+	try {
+		const text = JSON.stringify(value);
+		if (text !== void 0) return text;
+	} catch {}
+	try {
+		return String(value);
+	} catch {
+		return Object.prototype.toString.call(value);
+	}
+}
+/**
+* The form in which hostnames are compared: a URL hostname (lowercase ASCII,
+* IDNA as punycode, IPv6 in canonical form) without IPv6 brackets and without
+* one trailing dot.
+*/
+function comparableHost(hostname) {
+	return hostname.replace(/^\[(.*)\]$/, "$1").replace(/\.$/, "");
+}
+/**
+* Validates one `allowedHosts` entry and returns it in comparable form: an
+* exact host, or `*.` followed by a host suffix.
+*/
+function normalizeAllowedHost(entry) {
+	const invalid = (reason) => /* @__PURE__ */ new Error(`urlDownload.allowedHosts entry ${describeValue(entry)} is invalid: ${reason}`);
+	if (typeof entry !== "string" || entry === "") throw invalid("it must be a non-empty hostname");
+	if (/[\s/?#@\\]/.test(entry)) throw invalid("give only a hostname, without a scheme, path or user");
+	const wildcard = entry.startsWith("*.");
+	const host = wildcard ? entry.slice(2) : entry;
+	if (host === "" || host === "." || host.includes("*")) throw invalid("\"*\" is allowed only as a leading \"*.\" label");
+	if (/^[^:[\]]*:\d*$/.test(host) || /^\[.*\]:\d*$/.test(host)) throw invalid("give only a hostname, without a port");
+	const bare = host.replace(/^\[(.*)\]$/, "$1");
+	const authority = bare.includes(":") ? `[${bare}]` : host;
+	let parsed;
+	try {
+		parsed = new URL(`http://${authority}/`);
+	} catch {
+		throw invalid("it is not a valid hostname");
+	}
+	const normalized = comparableHost(parsed.hostname);
+	if (wildcard && (normalized.includes(":") || /^\d+\.\d+\.\d+\.\d+$/.test(normalized))) throw invalid("a wildcard needs a hostname suffix, not an IP address");
+	return (wildcard ? "*." : "") + normalized;
+}
+function normalizeAllowedHosts(entries) {
+	if (entries === void 0) return void 0;
+	if (!Array.isArray(entries)) throw new Error("urlDownload.allowedHosts must be an array of hostnames");
+	return entries.map(normalizeAllowedHost);
+}
+function hostAllowed(hostname, allowedHosts) {
+	if (!allowedHosts) return true;
+	const host = comparableHost(hostname);
+	return allowedHosts.some((pattern) => pattern.startsWith("*.") ? host.endsWith(pattern.slice(1)) && host.length > pattern.length - 1 : host === pattern);
+}
+function checkUrl(url, allowedHosts) {
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw refuse(url, "Only http and https URLs can be downloaded.");
+	if (url.username !== "" || url.password !== "") throw refuse(url, "URLs with credentials cannot be downloaded.");
+	if (!hostAllowed(url.hostname, allowedHosts)) throw refuse(url, "The URL host is not in the allowed hosts list.");
+}
+/**
+* Waits for `work`, or rejects with the abort reason when `signal` aborts.
+* The handlers are attached to `work` first, so that a later rejection of
+* `work` is always handled: an unhandled rejection ends a Node process in
+* the default mode.
+*/
+function withDeadline(work, signal) {
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		work.then(resolve, reject).finally(() => {
+			signal.removeEventListener("abort", onAbort);
+		});
+		if (signal.aborted) return onAbort();
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+async function requestPinned(modules, url, addresses, signal, ca) {
+	const lookup = (_hostname, options, callback) => {
+		const wanted = typeof options === "number" ? options : options?.family;
+		const available = wanted === 4 || wanted === 6 ? addresses.filter((a) => a.family === wanted) : addresses;
+		if (available.length === 0) callback(refuse(url, "No checked address is available for this URL."), "", 4);
+		else if (typeof options === "object" && options?.all) callback(null, available);
+		else callback(null, available[0].address, available[0].family);
+	};
+	const isHttps = url.protocol === "https:";
+	const transport = isHttps ? modules.https : modules.http;
+	const agent = isHttps ? new modules.https.Agent({
+		keepAlive: false,
+		maxCachedSessions: 0
+	}) : new modules.http.Agent({ keepAlive: false });
+	const hostname = url.hostname.replace(/^\[|\]$/g, "");
+	return new Promise((resolve, reject) => {
+		const request = transport.request({
+			protocol: url.protocol,
+			hostname,
+			servername: isHttps && modules.net.isIP(hostname) === 0 ? hostname.replace(/\.$/, "") : void 0,
+			port: url.port || (isHttps ? 443 : 80),
+			path: url.pathname + url.search,
+			method: "GET",
+			headers: {
+				"accept-encoding": "identity",
+				"user-agent": USER_AGENT
+			},
+			lookup,
+			agent,
+			signal,
+			...isHttps && ca !== void 0 ? { ca } : {}
+		}, (response) => {
+			response.once("close", () => agent.destroy());
+			resolve(response);
+		});
+		request.on("error", (error) => {
+			agent.destroy();
+			reject(error);
+		});
+		request.once("upgrade", (_response, socket) => {
+			socket.destroy();
+			agent.destroy();
+			reject(refuse(url, "Protocol upgrade refused."));
+		});
+		request.end();
+	});
+}
+async function readBody$1(url, response, maxBytes, budget) {
+	const tooLarge = () => refuse(url, `The response is larger than the ${maxBytes}-byte limit.`);
+	const overBudget = () => refuse(url, `The downloads are larger than the ${budget.limit}-byte total limit.`);
+	const declared = Number(response.headers["content-length"]);
+	if (Number.isFinite(declared) && declared > maxBytes) throw tooLarge();
+	if (Number.isFinite(declared) && declared > budget.remaining) throw overBudget();
+	const encoding = response.headers["content-encoding"];
+	if (encoding && encoding !== "identity") throw refuse(url, "Compressed responses are not accepted.");
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of response) {
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		total += buffer.byteLength;
+		if (total > maxBytes) throw tooLarge();
+		budget.remaining -= buffer.byteLength;
+		if (budget.remaining < 0) throw overBudget();
+		chunks.push(buffer);
+	}
+	return new Uint8Array(Buffer.concat(chunks, total));
+}
+async function downloadOne(original, options, internals, outer, budget) {
+	const modules = await loadNodeModules().catch((error) => {
+		throw refuse(original, "URL download needs Node.js networking modules, which are not available here.", `loading them failed: ${describeError(error)}. On a runtime without them, set urlDownload to "disabled" or to your own download function`);
+	});
+	defaultPolicy ??= buildAddressPolicy(modules.net);
+	const isPublic = internals.isPublicAddress ?? defaultPolicy;
+	const resolveHost = internals.resolveHost ?? ((hostname) => modules.dns.lookup(hostname, {
+		all: true,
+		verbatim: true
+	}));
+	let url = original;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(refuse(url, `The download timed out after ${options.timeoutMs} ms (timeoutMs).`)), options.timeoutMs);
+	const onOuterAbort = () => controller.abort(outer.reason);
+	if (outer.aborted) onOuterAbort();
+	else outer.addEventListener("abort", onOuterAbort, { once: true });
+	const { signal } = controller;
+	try {
+		for (let hop = 0;; hop++) {
+			signal.throwIfAborted();
+			checkUrl(url, options.allowedHosts);
+			const hostname = url.hostname.replace(/^\[|\]$/g, "");
+			const literalFamily = modules.net.isIP(hostname);
+			let addresses;
+			try {
+				signal.throwIfAborted();
+				addresses = literalFamily ? [{
+					address: hostname,
+					family: literalFamily
+				}] : await withDeadline(resolveHost(hostname), signal);
+			} catch (error) {
+				if (signal.aborted) throw signal.reason;
+				throw refuse(url, HOST_REFUSED, `DNS lookup failed: ${describeError(error)}`);
+			}
+			const verdicts = await Promise.all(addresses.map(async ({ address, family }) => (family === 4 || family === 6) && await isPublic(address) === true));
+			const rejected = addresses.filter((_address, i) => !verdicts[i]);
+			if (addresses.length === 0 || rejected.length > 0) throw refuse(url, HOST_REFUSED, addresses.length === 0 ? "DNS lookup returned no addresses" : `non-public address: ${rejected.map((a) => a.address).join(", ")}`);
+			let response;
+			try {
+				response = await requestPinned(modules, url, addresses, signal, internals.ca);
+			} catch (error) {
+				if (signal.aborted) throw signal.reason;
+				if (DownloadError.isInstance(error)) throw error;
+				throw refuse(url, DOWNLOAD_FAILED, describeError(error));
+			}
+			try {
+				const status = response.statusCode ?? 0;
+				if (REDIRECT_STATUSES.has(status)) {
+					if (hop >= options.maxRedirects) throw refuse(url, `Too many redirects: the limit is ${options.maxRedirects} (maxRedirects).`);
+					const location = response.headers.location;
+					if (!location) throw refuse(url, "Redirect without a location.");
+					let next;
+					try {
+						next = new URL(location, url);
+					} catch (error) {
+						throw refuse(url, "Redirect to an invalid URL.", `Location ${JSON.stringify(location.slice(0, 200))}: ${describeError(error)}`);
+					}
+					if (url.protocol === "https:" && next.protocol === "http:") throw refuse(url, "A redirect from https to http is refused.");
+					url = next;
+					continue;
+				}
+				if (status < 200 || status >= 300) throw refuse(url, `The server answered with HTTP status ${status}.`, response.statusMessage, status);
+				return {
+					data: await readBody$1(url, response, options.maxBytes, budget),
+					mediaType: response.headers["content-type"] || void 0
+				};
+			} catch (error) {
+				if (signal.aborted) throw signal.reason;
+				if (DownloadError.isInstance(error)) throw error;
+				throw refuse(url, DOWNLOAD_FAILED, describeError(error));
+			} finally {
+				response.destroy();
+			}
+		}
+	} finally {
+		clearTimeout(timer);
+		outer.removeEventListener("abort", onOuterAbort);
+		controller.abort();
+	}
+}
+const MAX_TIMEOUT_MS = 2147483647;
+/** Returns `value` (or `fallback`) if it is an integer from `min` to `max`. */
+function integerOption(name, value, fallback, min, max = Number.MAX_SAFE_INTEGER) {
+	const result = value ?? fallback;
+	if (!Number.isSafeInteger(result) || result < min || result > max) {
+		const range = max === Number.MAX_SAFE_INTEGER ? `an integer of at least ${min}` : `an integer from ${min} to ${max}`;
+		throw new Error(`urlDownload.${name} must be ${range}, got ${describeValue(value)}`);
+	}
+	return result;
+}
+const OPTION_NAMES = {
+	allowedHosts: true,
+	maxBytes: true,
+	timeoutMs: true,
+	maxRedirects: true,
+	maxDownloads: true,
+	maxTotalBytes: true
+};
+function checkOptionsObject(options) {
+	if (typeof options !== "object" || options === null || Array.isArray(options)) throw new Error(`urlDownload options must be an object, got ${describeValue(options)}`);
+}
+function checkOptionNames(options) {
+	checkOptionsObject(options);
+	for (const name of Object.keys(options)) if (!Object.prototype.hasOwnProperty.call(OPTION_NAMES, name)) throw new Error(`urlDownload has an unknown option ${describeValue(name)}; the valid options are ${Object.keys(OPTION_NAMES).join(", ")}`);
+}
+/** @internal Factory with test seams; use {@link createSafeUrlDownload}. */
+function createGuardedUrlDownload(options = {}, internals = {}) {
+	checkOptionNames(options);
+	const resolved = {
+		allowedHosts: normalizeAllowedHosts(options.allowedHosts),
+		maxBytes: integerOption("maxBytes", options.maxBytes, DEFAULT_MAX_BYTES, 1),
+		timeoutMs: integerOption("timeoutMs", options.timeoutMs, DEFAULT_TIMEOUT_MS, 1, MAX_TIMEOUT_MS),
+		maxRedirects: integerOption("maxRedirects", options.maxRedirects, DEFAULT_MAX_REDIRECTS, 0),
+		maxDownloads: integerOption("maxDownloads", options.maxDownloads, DEFAULT_MAX_DOWNLOADS, 1),
+		maxTotalBytes: integerOption("maxTotalBytes", options.maxTotalBytes, DEFAULT_MAX_TOTAL_BYTES, 1)
+	};
+	const downloadAll = async (requests, runSignal) => {
+		const batch = new AbortController();
+		const onRunAbort = () => batch.abort(runSignal?.reason);
+		if (runSignal?.aborted) onRunAbort();
+		else runSignal?.addEventListener("abort", onRunAbort, { once: true });
+		try {
+			const pending = /* @__PURE__ */ new Map();
+			for (const request of requests) if (!leftToAiSdk(request)) pending.set(request.url.href, request.url);
+			if (pending.size > resolved.maxDownloads) throw refuse([...pending.values()][resolved.maxDownloads], `A model call can have at most ${resolved.maxDownloads} URL downloads; this one has ${pending.size}.`);
+			const budget = {
+				remaining: resolved.maxTotalBytes,
+				limit: resolved.maxTotalBytes
+			};
+			const downloads = new Map([...pending].map(([href, url]) => [href, downloadOne(url, resolved, internals, batch.signal, budget).catch((error) => {
+				batch.abort(error);
+				throw error;
+			})]));
+			return await Promise.all(requests.map((request) => leftToAiSdk(request) ? null : downloads.get(request.url.href)));
+		} finally {
+			runSignal?.removeEventListener("abort", onRunAbort);
+			batch.abort();
+		}
+	};
+	return Object.assign((requests) => downloadAll(requests), { forRun: (signal) => (requests) => downloadAll(requests, signal) });
+}
+/**
+* @internal Resolves BuiltInAgent's `urlDownload` setting once, so that an
+* invalid setting fails when the agent is constructed. The result gives the
+* download function for one run; the default downloader stops when the run
+* is aborted.
+*/
+function resolveUrlDownloadSetting(setting) {
+	if (setting === "disabled") return () => disabledUrlDownload;
+	if (typeof setting === "function") return () => setting;
+	if (setting === void 0 || setting === null) return createGuardedUrlDownload().forRun;
+	if (typeof setting === "object" && !Array.isArray(setting)) return createGuardedUrlDownload(setting).forRun;
+	throw new Error(`urlDownload must be "disabled", an options object or a download function, got ${describeValue(setting)}`);
+}
+/**
+* Creates an AI SDK download function (`experimental_download`) that only
+* fetches public internet addresses, with the same checks and limits as
+* BuiltInAgent's default downloader. Pass it to `streamText` yourself when
+* you use BuiltInAgent's AI SDK factory mode. Create it in the factory with
+* the run's abort signal, so that an aborted run stops its downloads:
+*
+* ```ts
+* import { createSafeUrlDownload } from "@copilotkit/runtime/v2";
+*
+* factory: (ctx) =>
+*   streamText({
+*     model,
+*     messages,
+*     abortSignal: ctx.abortSignal,
+*     experimental_download: createSafeUrlDownload({ signal: ctx.abortSignal }),
+*   }),
+* ```
+*
+* Invalid options throw here, when the function is created.
+*/
+function createSafeUrlDownload(options = {}) {
+	checkOptionsObject(options);
+	const { signal, ...downloadOptions } = options;
+	if (signal !== void 0 && !(signal instanceof AbortSignal)) throw new Error(`urlDownload signal must be an AbortSignal, got ${describeValue(signal)}`);
+	const download = createGuardedUrlDownload(downloadOptions);
+	return signal ? download.forRun(signal) : download;
+}
+/**
+* A download function that never fetches from the network. URLs that the
+* model takes as-is and `data:` URLs are left to the AI SDK; any other URL,
+* whatever its scheme, fails the run.
+*/
+const disabledUrlDownload = async (requests) => requests.map((request) => {
+	if (leftToAiSdk(request)) return null;
+	throw refuse(request.url, "Server-side URL download is disabled (urlDownload: \"disabled\").");
+});
+
+//#endregion
+export { createSafeUrlDownload, logModelCallError, resolveUrlDownloadSetting };
+//# sourceMappingURL=url-download.mjs.map