@assistant-ui/x-generative-compiler 0.0.2 → 0.0.4

package/dist/compile.js

@@ -1,11 +1,39 @@
 import { DIRECTIVE } from "./constants.js";
+import { version } from "./package.js";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as nodePath from "node:path";
 import { parse } from "@babel/parser";
 import _traverse from "@babel/traverse";
 import _generate from "@babel/generator";
 import * as t from "@babel/types";
+import { satisfies } from "semver";
 //#region src/compile.ts
 const traverse = typeof _traverse === "function" ? _traverse : _traverse.default;
 const generate = typeof _generate === "function" ? _generate : _generate.default;
+/** The required wrapper around a toolkit's tools (stripped at build time). */
+const TOOLKIT_WRAPPER = "defineToolkit";
+/** The helper that produces MCP-only toolkit fragments. */
+const MCP_TOOLKIT_WRAPPER = "defineMcpToolkit";
+/** The required wrapper around a generative-UI library (stripped at build time). */
+const COMPONENTS_WRAPPER = "defineGenerativeComponents";
+/** The core package whose metadata declares supported compiler versions. */
+const CORE_PACKAGE = "@assistant-ui/core";
+/** This package, checked against core's compatibility range. */
+const COMPILER_PACKAGE = "@assistant-ui/x-generative-compiler";
+/** Packages that re-export core's generative markers. */
+const DISTRIBUTION_PACKAGES = [
+	CORE_PACKAGE,
+	"@assistant-ui/react",
+	"@assistant-ui/react-native",
+	"@assistant-ui/react-ink"
+];
+/**
+* The class whose instances expose split-by-condition tools (`present()`,
+* `promptUser()`). A toolkit entry that calls a method on one of these passes
+* through untouched — the library, not this compiler, routes its halves.
+*/
+const GENERATIVE_FACTORY = "JSONGenerativeUI";
 /** Thrown when a `"use generative"` file violates an authoring constraint. */
 var GenerativeCompileError = class extends Error {
 	constructor(message, filename) {
@@ -45,27 +73,32 @@ function compileGenerative(code, options) {
 		]
 	});
 	if (!ast.program.directives.some((d) => d.value.value === "use generative")) throw new GenerativeCompileError(`missing "${DIRECTIVE}" directive`, filename);
-	const object = findDefaultExportObject(ast, filename);
-	let keptRender = false;
-	let keptBackendExecute = false;
-	for (const entry of object.properties) {
-		const value = entryValue(entry);
-		if (!value) throw new GenerativeCompileError("each tool must be an inline object literal (`name: { ... }`) so its `execute` can be routed", filename);
-		const type = inferToolType(value, filename);
-		const hasRender = !!findMember(value, "render");
-		const execute = findMember(value, "execute");
-		if ((type === "frontend" || type === "human") && !hasRender) throw new GenerativeCompileError(`a ${type} tool must declare a \`render\` (it has no server execute to show otherwise)`, filename);
-		if (target === "client") {
-			if (execute && type === "frontend") stripUseClient(execute);
-			else if (execute) removeMember(value, "execute");
-			if (hasRender) keptRender = true;
-		} else {
-			if (hasRender) removeMember(value, "render");
-			if (execute && type !== "backend") removeMember(value, "execute");
-			if (execute && type === "backend") keptBackendExecute = true;
+	ensureCompilerCompatibleWithCore(ast, filename);
+	ensureDefaultExport(ast, filename);
+	const generativeInstances = collectGenerativeInstances(ast);
+	const safeToolkitSpreads = collectSafeToolkitSpreads(ast, filename);
+	const flags = {
+		keptRender: false,
+		keptBackendExecute: false
+	};
+	traverse(ast, { CallExpression(path) {
+		const callee = path.node.callee;
+		const object = t.isObjectExpression(path.node.arguments[0]) ? path.node.arguments[0] : null;
+		if (t.isIdentifier(callee, { name: COMPONENTS_WRAPPER })) {
+			if (!object) throw new GenerativeCompileError(`${COMPONENTS_WRAPPER}() takes an inline object literal of components`, filename);
+			compileComponents(object, target, flags, filename);
+			path.replaceWith(object);
+			path.skip();
+			return;
 		}
-		setToolType(value, type);
-	}
+		if (t.isIdentifier(callee, { name: TOOLKIT_WRAPPER })) {
+			if (!object) throw new GenerativeCompileError(`${TOOLKIT_WRAPPER}() takes an inline object literal of tools`, filename);
+			compileToolkit(object, target, generativeInstances, safeToolkitSpreads, flags, filename);
+			path.replaceWith(object);
+			path.skip();
+		}
+	} });
+	const { keptRender, keptBackendExecute } = flags;
 	pruneUnused(ast);
 	ast.program.directives = ast.program.directives.filter((d) => d.value.value !== "use generative" && d.value.value !== "use client");
 	if (target === "client" && keptRender) ast.program.directives.unshift(t.directive(t.directiveLiteral("use client")));
@@ -80,29 +113,453 @@ function compileGenerative(code, options) {
 		map: result.map
 	};
 }
-function findDefaultExportObject(ast, filename) {
-	let object = null;
-	let sawDefault = false;
-	for (const stmt of ast.program.body) {
-		if (!t.isExportDefaultDeclaration(stmt)) continue;
-		sawDefault = true;
-		object = unwrapDefineToolkit(stmt.declaration);
-		if (object) stmt.declaration = object;
-	}
-	if (!sawDefault) throw new GenerativeCompileError("missing a default export", filename);
-	if (!object) throw new GenerativeCompileError("the default export must be `defineToolkit({ ... })` (imported from \"@assistant-ui/react\"); wrapping is required so a backend `execute` can't be authored in a way that reaches the client", filename);
-	return object;
-}
-/**
-* Unwraps the required `defineToolkit({ ... })` wrapper (through `satisfies`/`as`
-* and parens) to the underlying object literal. Anything else — a bare object, a
-* `satisfies Toolkit` without the wrapper, some other call — yields `null` so the
-* caller errors.
-*/
-function unwrapDefineToolkit(node) {
-	if (t.isTSSatisfiesExpression(node) || t.isTSAsExpression(node)) return unwrapDefineToolkit(node.expression);
-	if (t.isParenthesizedExpression(node)) return unwrapDefineToolkit(node.expression);
-	if (t.isCallExpression(node) && t.isIdentifier(node.callee, { name: "defineToolkit" }) && t.isObjectExpression(node.arguments[0])) return node.arguments[0];
+const checkedCorePackageJsonPaths = /* @__PURE__ */ new Set();
+const COMPILER_VERSION = version;
+function ensureCompilerCompatibleWithCore(ast, filename) {
+	const corePackageJsonPath = resolveCorePackageJson(ast, filename);
+	if (!corePackageJsonPath || checkedCorePackageJsonPaths.has(corePackageJsonPath)) return;
+	const corePackageJson = readPackageJson(corePackageJsonPath);
+	const range = corePackageJson?.optionalDevDependencies?.[COMPILER_PACKAGE];
+	if (!range) {
+		checkedCorePackageJsonPaths.add(corePackageJsonPath);
+		return;
+	}
+	let compatible = false;
+	try {
+		compatible = satisfies(COMPILER_VERSION, range, { includePrerelease: true });
+	} catch {
+		throw new GenerativeCompileError(`${CORE_PACKAGE}@${corePackageJson.version ?? "unknown"} declares an invalid optionalDevDependencies range for ${COMPILER_PACKAGE}: ` + JSON.stringify(range), filename);
+	}
+	if (!compatible) throw new GenerativeCompileError(`${CORE_PACKAGE}@${corePackageJson.version ?? "unknown"} requires ${COMPILER_PACKAGE} ${range}, but the current compiler is ${COMPILER_VERSION}. Update @assistant-ui/next, @assistant-ui/vite, or @assistant-ui/metro so their compiler satisfies the core package's optionalDevDependencies range.`, filename);
+	checkedCorePackageJsonPaths.add(corePackageJsonPath);
+}
+function resolveCorePackageJson(ast, filename) {
+	for (const packageName of collectImportedDistributionPackages(ast)) {
+		const packageJsonPath = resolvePackageJson(packageName, filename);
+		if (!packageJsonPath) continue;
+		if (packageName === CORE_PACKAGE) return packageJsonPath;
+		const corePackageJsonPath = resolvePackageJson(CORE_PACKAGE, packageJsonPath);
+		if (corePackageJsonPath) return corePackageJsonPath;
+	}
+	return null;
+}
+function collectImportedDistributionPackages(ast) {
+	const packages = /* @__PURE__ */ new Set();
+	for (const statement of ast.program.body) {
+		const source = (t.isImportDeclaration(statement) || t.isExportNamedDeclaration(statement) || t.isExportAllDeclaration(statement)) && statement.source ? statement.source.value : null;
+		if (!source) continue;
+		const packageName = packageNameFromSpecifier(source);
+		if (packageName) packages.add(packageName);
+	}
+	return packages;
+}
+function packageNameFromSpecifier(specifier) {
+	for (const packageName of DISTRIBUTION_PACKAGES) if (specifier === packageName || specifier.startsWith(`${packageName}/`)) return packageName;
+	return null;
+}
+function resolvePackageJson(packageName, filename) {
+	const requirePath = normalizeRequirePath(filename);
+	const require = createRequire(requirePath);
+	try {
+		return findPackageJson(require.resolve(packageName), packageName);
+	} catch {
+		return findPackageJsonFromNodeModules(packageName, requirePath);
+	}
+}
+function normalizeRequirePath(filename) {
+	return cleanAbsoluteFilename(filename) ?? import.meta.url;
+}
+/** Strips a `?query`/`#hash` suffix and returns the path only if it is absolute. */
+function cleanAbsoluteFilename(filename) {
+	if (!filename) return null;
+	const clean = filename.split(/[?#]/, 1)[0];
+	return nodePath.isAbsolute(clean) ? clean : null;
+}
+function findPackageJson(fromPathOrUrl, packageName) {
+	let current = nodePath.dirname(fromPathOrUrl.startsWith("file:") ? new URL(fromPathOrUrl).pathname : nodePath.resolve(fromPathOrUrl));
+	for (;;) {
+		const packageJsonPath = nodePath.join(current, "package.json");
+		if (readPackageJson(packageJsonPath)?.name === packageName) return packageJsonPath;
+		const parent = nodePath.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+function findPackageJsonFromNodeModules(packageName, fromPathOrUrl) {
+	const parts = packageName.split("/");
+	let current = nodePath.dirname(fromPathOrUrl.startsWith("file:") ? new URL(fromPathOrUrl).pathname : nodePath.resolve(fromPathOrUrl));
+	for (;;) {
+		const packageJsonPath = nodePath.join(current, "node_modules", ...parts, "package.json");
+		if (readPackageJson(packageJsonPath)?.name === packageName) return packageJsonPath;
+		const parent = nodePath.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+function readPackageJson(packageJsonPath) {
+	if (!existsSync(packageJsonPath)) return null;
+	try {
+		return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	} catch (error) {
+		throw new GenerativeCompileError(`could not parse package metadata at ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Errors unless the module's default export is the toolkit — a `defineToolkit(...)`
+* call (through `satisfies`/`as`/parens). This is the security boundary: the
+* default export is what the runtime registers, so it must be wrapped (and thus
+* split). A bare `export default { ... }` would ship a backend `execute` to the
+* client even if some *other* `defineToolkit(...)` exists elsewhere in the file.
+*/
+function ensureDefaultExport(ast, filename) {
+	const def = ast.program.body.find((stmt) => t.isExportDefaultDeclaration(stmt));
+	if (!def) throw new GenerativeCompileError("missing a default export", filename);
+	if (!unwrapToToolkitCall(def.declaration)) throw new GenerativeCompileError(`the default export must be ${TOOLKIT_WRAPPER}({ ... }) or ${MCP_TOOLKIT_WRAPPER}({ ... }) (imported from "@assistant-ui/react"); wrapping is required so a backend \`execute\` can't be authored in a way that reaches the client`, filename);
+}
+/**
+* Unwraps a node through `satisfies`/`as`/parens to a call of the named function,
+* or returns `null`.
+*/
+function unwrapToCall(node, name) {
+	if (t.isTSSatisfiesExpression(node) || t.isTSAsExpression(node)) return unwrapToCall(node.expression, name);
+	if (t.isParenthesizedExpression(node)) return unwrapToCall(node.expression, name);
+	if (t.isCallExpression(node) && t.isIdentifier(node.callee, { name })) return node;
+	return null;
+}
+/**
+* Collects the names bound to `new JSONGenerativeUI(...)` (e.g.
+* `const generative = new JSONGenerativeUI({ library })`). A toolkit entry that
+* calls a method on one of these is a generative tool whose halves the library
+* routes by export condition, so it passes through the toolkit pass untouched.
+*/
+function collectGenerativeInstances(ast) {
+	const names = /* @__PURE__ */ new Set();
+	for (const statement of ast.program.body) {
+		if (!t.isVariableDeclaration(statement)) continue;
+		for (const declaration of statement.declarations) {
+			const { id, init } = declaration;
+			if (t.isIdentifier(id) && t.isNewExpression(init) && t.isIdentifier(init.callee, { name: GENERATIVE_FACTORY })) names.add(id.name);
+		}
+	}
+	return names;
+}
+/**
+* Toolkit identifiers that are safe to spread into a `defineToolkit({ ... })`.
+*
+* Two kinds qualify:
+*
+* - A local variable whose initializer is visible to this compiler pass: a
+*   `defineToolkit(...)` binding is compiled in-place before a later spread
+*   reads it, and `defineMcpToolkit(...)` entries can't contain executable code.
+* - The default import of another `"use generative"` module: that module is
+*   split per-target by its own compiler pass, so spreading its default-exported
+*   toolkit can't leak a backend `execute` to the client. Only the default
+*   export crosses the generative-module boundary, so named imports don't
+*   qualify — they would be `undefined` once that module is build-split.
+*/
+function collectSafeToolkitSpreads(ast, filename) {
+	const names = /* @__PURE__ */ new Set();
+	const generativeBySource = /* @__PURE__ */ new Map();
+	for (const statement of ast.program.body) {
+		if (t.isVariableDeclaration(statement)) {
+			for (const declaration of statement.declarations) {
+				const { id, init } = declaration;
+				if (t.isIdentifier(id) && init && unwrapToToolkitCall(init)) names.add(id.name);
+			}
+			continue;
+		}
+		if (t.isImportDeclaration(statement)) {
+			const defaultSpecifier = statement.specifiers.find((specifier) => t.isImportDefaultSpecifier(specifier));
+			if (!defaultSpecifier) continue;
+			const source = statement.source.value;
+			let isGenerative = generativeBySource.get(source);
+			if (isGenerative === void 0) {
+				isGenerative = isGenerativeImport(source, filename);
+				generativeBySource.set(source, isGenerative);
+			}
+			if (isGenerative) names.add(defaultSpecifier.local.name);
+		}
+	}
+	return names;
+}
+const MODULE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+];
+/** Extensions a specifier may carry that actually map to a TS source file. */
+const REWRITABLE_JS_EXTENSIONS = new Set([
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+]);
+/**
+* Whether an import specifier resolves on disk to a `"use generative"` module.
+* Relative specifiers and `tsconfig` path aliases (e.g. `@/tools`) are resolved;
+* anything else (a bare package, an unresolvable alias) is treated as
+* non-generative, and thus an unsafe spread.
+*/
+function isGenerativeImport(source, filename) {
+	const cleanFilename = cleanAbsoluteFilename(filename);
+	if (!cleanFilename) return false;
+	const resolved = resolveImportedModuleFile(source, cleanFilename);
+	if (!resolved) return false;
+	try {
+		return isGenerativeModule(readFileSync(resolved, "utf8"));
+	} catch {
+		return false;
+	}
+}
+/** Resolves an import specifier (relative or `tsconfig`-aliased) to a file on disk. */
+function resolveImportedModuleFile(source, fromFilename) {
+	if (source.startsWith(".")) return resolveModuleFileAtPath(nodePath.resolve(nodePath.dirname(fromFilename), source));
+	return resolveAliasImport(source, fromFilename);
+}
+/**
+* Resolves a candidate module path, trying TS/JS extensions then index files. A
+* specifier may carry a `.js`-family extension that maps to a `.ts`/`.tsx`
+* source (TypeScript's `bundler`/`nodenext` resolution), so the extension is
+* dropped before probing.
+*/
+function resolveModuleFileAtPath(base) {
+	const ext = nodePath.extname(base);
+	if (ext && existsSync(base)) return base;
+	const stem = REWRITABLE_JS_EXTENSIONS.has(ext) ? base.slice(0, -ext.length) : base;
+	for (const candidateExt of MODULE_EXTENSIONS) {
+		const candidate = `${stem}${candidateExt}`;
+		if (existsSync(candidate)) return candidate;
+	}
+	for (const candidateExt of MODULE_EXTENSIONS) {
+		const candidate = nodePath.join(base, `index${candidateExt}`);
+		if (existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+/** Resolves a `tsconfig` path alias (e.g. `@/tools/x`) to a file on disk. */
+function resolveAliasImport(source, fromFilename) {
+	const tsconfig = loadTsconfigAliases(nodePath.dirname(fromFilename));
+	if (!tsconfig) return null;
+	const patterns = Object.entries(tsconfig.paths).sort(([a], [b]) => aliasSpecificity(b) - aliasSpecificity(a));
+	for (const [pattern, targets] of patterns) {
+		const matched = matchAliasPattern(pattern, source);
+		if (matched === null) continue;
+		for (const target of targets) {
+			const specifier = substituteAliasWildcard(target, matched);
+			const file = resolveModuleFileAtPath(nodePath.resolve(tsconfig.baseDir, specifier));
+			if (file) return file;
+		}
+	}
+	return null;
+}
+/** Ranks a `paths` key: an exact key outranks any wildcard; longer prefixes win. */
+function aliasSpecificity(pattern) {
+	const star = pattern.indexOf("*");
+	return star === -1 ? pattern.length + 1 : star;
+}
+/** Substitutes the single `*` in a `paths` target with the matched text. */
+function substituteAliasWildcard(target, matched) {
+	const star = target.indexOf("*");
+	if (star === -1) return target;
+	return target.slice(0, star) + matched + target.slice(star + 1);
+}
+/**
+* Matches an import specifier against a `tsconfig` `paths` key. Returns the text
+* captured by the key's `*` (or `""` for an exact, wildcard-free key), or `null`
+* when the specifier doesn't match.
+*/
+function matchAliasPattern(pattern, source) {
+	const star = pattern.indexOf("*");
+	if (star === -1) return pattern === source ? "" : null;
+	const prefix = pattern.slice(0, star);
+	const suffix = pattern.slice(star + 1);
+	if (source.length >= prefix.length + suffix.length && source.startsWith(prefix) && source.endsWith(suffix)) return source.slice(prefix.length, source.length - suffix.length);
+	return null;
+}
+/**
+* Memoizes resolved aliases per start directory. The compiler runs once per
+* file across a build, so without this every aliased spread re-walks and
+* re-parses the same `tsconfig.json`. Process-lifetime, like
+* `checkedCorePackageJsonPaths`.
+*/
+const tsconfigAliasesByDir = /* @__PURE__ */ new Map();
+/** Walks up from a directory to the nearest `tsconfig.json` that declares `paths`. */
+function loadTsconfigAliases(fromDir) {
+	const cached = tsconfigAliasesByDir.get(fromDir);
+	if (cached !== void 0) return cached;
+	let aliases = null;
+	let dir = fromDir;
+	for (;;) {
+		const tsconfigPath = nodePath.join(dir, "tsconfig.json");
+		if (existsSync(tsconfigPath)) {
+			aliases = readTsconfigAliases(tsconfigPath, /* @__PURE__ */ new Set());
+			if (aliases) break;
+		}
+		const parent = nodePath.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	tsconfigAliasesByDir.set(fromDir, aliases);
+	return aliases;
+}
+/** Reads `baseUrl`/`paths` from a tsconfig, following a single `extends` chain. */
+function readTsconfigAliases(tsconfigPath, seen) {
+	if (seen.has(tsconfigPath)) return null;
+	seen.add(tsconfigPath);
+	let config;
+	try {
+		config = parseJsonc(readFileSync(tsconfigPath, "utf8"));
+	} catch {
+		return null;
+	}
+	if (!config) return null;
+	const configDir = nodePath.dirname(tsconfigPath);
+	const { baseUrl, paths } = config.compilerOptions ?? {};
+	if (paths) return {
+		baseDir: baseUrl ? nodePath.resolve(configDir, baseUrl) : configDir,
+		paths
+	};
+	const extendsList = Array.isArray(config.extends) ? config.extends : config.extends ? [config.extends] : [];
+	for (let i = extendsList.length - 1; i >= 0; i--) {
+		const entry = extendsList[i];
+		if (typeof entry !== "string") continue;
+		const extended = resolveExtendedTsconfig(entry, configDir);
+		if (extended) {
+			const aliases = readTsconfigAliases(extended, seen);
+			if (aliases) return aliases;
+		}
+	}
+	return null;
+}
+/** Resolves a tsconfig `extends` value (relative path or installed package). */
+function resolveExtendedTsconfig(extendsValue, configDir) {
+	if (extendsValue.startsWith(".")) {
+		const base = nodePath.resolve(configDir, extendsValue);
+		return (nodePath.extname(base) === ".json" ? [base] : [`${base}.json`, base]).find((candidate) => existsSync(candidate)) ?? null;
+	}
+	try {
+		return createRequire(nodePath.join(configDir, "package.json")).resolve(extendsValue.endsWith(".json") ? extendsValue : `${extendsValue}.json`);
+	} catch {
+		return null;
+	}
+}
+/** Parses JSON with `//` and block comments and trailing commas stripped (tsconfig is JSONC). */
+function parseJsonc(text) {
+	const withoutTrailingCommas = text.replace(/"(?:[^"\\]|\\.)*"|\/\/[^\n\r]*|\/\*[\s\S]*?\*\//g, (match) => match.startsWith("\"") ? match : "").replace(/,(\s*[}\]])/g, "$1");
+	return JSON.parse(withoutTrailingCommas);
+}
+function unwrapToToolkitCall(node) {
+	return unwrapToCall(node, TOOLKIT_WRAPPER) ?? unwrapToCall(node, MCP_TOOLKIT_WRAPPER);
+}
+function isSafeToolkitSpread(entry, safeToolkitSpreads) {
+	if (t.isIdentifier(entry.argument)) return safeToolkitSpreads.has(entry.argument.name);
+	const directMcpToolkit = unwrapToCall(entry.argument, MCP_TOOLKIT_WRAPPER);
+	return !!directMcpToolkit && t.isObjectExpression(directMcpToolkit.arguments[0]);
+}
+/** The `JSONGenerativeUI` methods that produce a split-by-condition tool. */
+const GENERATIVE_TOOL_METHODS = new Set(["present", "promptUser"]);
+/**
+* Whether a toolkit entry's value is a call to a tool-producing method on a
+* collected `JSONGenerativeUI` instance (`generative.present()`), which passes
+* through. The method name is checked too, so a typo like `generative.presnt()`
+* is a compile error here rather than a pass-through that fails at runtime.
+*/
+function isGenerativeToolEntry(value, instances) {
+	return t.isCallExpression(value) && t.isMemberExpression(value.callee) && !value.callee.computed && t.isIdentifier(value.callee.object) && instances.has(value.callee.object.name) && t.isIdentifier(value.callee.property) && GENERATIVE_TOOL_METHODS.has(value.callee.property.name);
+}
+/**
+* Splits a `defineGenerativeComponents({ ... })` library for a build target:
+* a component's `render` (and the client imports it alone uses) is dropped on
+* the server; `properties`/`description` stay on both, since they drive the tool
+* schema either way. Mutates the object in place.
+*/
+function compileComponents(object, target, flags, filename) {
+	for (const entry of object.properties) {
+		const value = entryValue(entry);
+		if (!value) throw new GenerativeCompileError(`each component in ${COMPONENTS_WRAPPER}() must be an inline object literal (\`name: { ... }\`) so its \`render\` can be routed`, filename);
+		if (!findMember(value, "render")) continue;
+		if (target === "client") flags.keptRender = true;
+		else removeMember(value, "render");
+	}
+}
+/**
+* Splits a `defineToolkit({ ... })` for a build target. Each inline tool is
+* routed by inferred type (see the per-entry logic); a generative entry like
+* `generative.present()` passes through, the library having already split it.
+* Mutates the object in place and records outcomes in {@link TargetFlags}.
+*/
+function compileToolkit(object, target, instances, safeToolkitSpreads, flags, filename) {
+	const nextProperties = [];
+	for (const entry of object.properties) {
+		const value = entryValue(entry);
+		if (!value) {
+			if (t.isSpreadElement(entry) && isSafeToolkitSpread(entry, safeToolkitSpreads)) {
+				nextProperties.push(entry);
+				continue;
+			}
+			const raw = entryRawValue(entry);
+			if (raw && isGenerativeToolEntry(raw, instances)) {
+				nextProperties.push(entry);
+				continue;
+			}
+			throw new GenerativeCompileError("each tool must be an inline object literal (`name: { ... }`) or a compiler-visible toolkit spread / generative tool (e.g. `...defineMcpToolkit(...)`, `...baseToolkit`, or `generative.present()`) so its `execute` can be routed", filename);
+		}
+		const execute = findMember(value, "execute");
+		const isStub = execute ? executeIsStubTool(execute) : false;
+		const isExternal = execute ? executeIsExternalTool(execute) : false;
+		const type = inferToolType(value, filename);
+		const hasRender = !!findMember(value, "render");
+		const hasRenderText = !!findMember(value, "renderText");
+		if (type === "frontend" && !hasRender && !hasRenderText) throw new GenerativeCompileError("a frontend tool must declare a `render` or `renderText` (it has no server execute to show otherwise)", filename);
+		if (type === "human" && !hasRender) throw new GenerativeCompileError("a human tool must declare a `render` so it can collect input", filename);
+		if (type === "provider" && execute) applyProviderToolConfig(value, execute, filename);
+		if (isExternal) {
+			if (!hasRender && !hasRenderText) throw new GenerativeCompileError("an external tool must declare a `render` or `renderText` (assistant-ui only renders calls for tools defined elsewhere)", filename);
+			if (target === "server") continue;
+			stripExternalToolMetadata(value);
+		}
+		if (target === "client") {
+			if (execute && type === "frontend" && !isStub) stripUseClient(execute);
+			else if (execute) removeMember(value, "execute");
+			if (hasRender || hasRenderText) flags.keptRender = true;
+		} else {
+			if (hasRender) removeMember(value, "render");
+			if (hasRenderText) removeMember(value, "renderText");
+			if (execute) if (type === "backend" && !isExternal) flags.keptBackendExecute = true;
+			else removeMember(value, "execute");
+		}
+		setToolType(value, type);
+		setBackendDefault(value, target, type);
+		nextProperties.push(entry);
+	}
+	object.properties = nextProperties;
+}
+function applyProviderToolConfig(object, execute, filename) {
+	if (!t.isObjectProperty(execute) || !t.isCallExpression(execute.value) || execute.value.arguments.length !== 1 || !t.isObjectExpression(execute.value.arguments[0])) throw new GenerativeCompileError("`providerTool(...)` must receive an inline object literal", filename);
+	const existingNames = new Set(object.properties.flatMap((prop) => {
+		if (!t.isObjectProperty(prop) && !t.isObjectMethod(prop)) return [];
+		const name = memberName(prop.key, prop.computed);
+		return name ? [name] : [];
+	}));
+	const configNames = /* @__PURE__ */ new Set();
+	for (const prop of execute.value.arguments[0].properties) {
+		if (!t.isObjectProperty(prop)) throw new GenerativeCompileError("`providerTool(...)` config can only contain object properties", filename);
+		const name = memberName(prop.key, prop.computed);
+		if (!name) throw new GenerativeCompileError("`providerTool(...)` config can only contain static property names", filename);
+		if (t.isFunctionExpression(prop.value) || t.isArrowFunctionExpression(prop.value)) throw new GenerativeCompileError("`providerTool(...)` config cannot contain function-valued properties", filename);
+		if (existingNames.has(name) || configNames.has(name)) throw new GenerativeCompileError("`providerTool(...)` config cannot duplicate tool properties", filename);
+		configNames.add(name);
+		object.properties.push(prop);
+	}
+}
+/** The raw AST value of an entry (any expression), or null for spreads/methods. */
+function entryRawValue(entry) {
+	if (t.isObjectProperty(entry) && t.isExpression(entry.value)) return entry.value;
 	return null;
 }
 function entryValue(entry) {
@@ -126,9 +583,24 @@ function executeBody(member) {
 function executeIsClient(member) {
 	return !!executeBody(member)?.directives.some((d) => d.value.value === "use client");
 }
-/** Whether an `execute` is the `hitl()` human-in-the-loop sentinel. */
-function executeIsHitl(member) {
-	return t.isObjectProperty(member) && t.isCallExpression(member.value) && t.isIdentifier(member.value.callee, { name: "hitl" });
+function executeIsSentinel(member, name) {
+	return t.isObjectProperty(member) && t.isCallExpression(member.value) && t.isIdentifier(member.value.callee, { name });
+}
+/** Whether an `execute` is the human-in-the-loop sentinel. */
+function executeIsHumanTool(member) {
+	return executeIsSentinel(member, "humanTool") || executeIsSentinel(member, "hitlTool") || executeIsSentinel(member, "hitl");
+}
+/** Whether an `execute` is the provider-tool sentinel. */
+function executeIsProviderTool(member) {
+	return executeIsSentinel(member, "providerTool");
+}
+/** Whether an `execute` is the local override sentinel. */
+function executeIsStubTool(member) {
+	return executeIsSentinel(member, "stubTool");
+}
+/** Whether an `execute` is the externally-defined backend tool sentinel. */
+function executeIsExternalTool(member) {
+	return executeIsSentinel(member, "externalTool");
 }
 /** Drops the `"use client"` directive from an `execute` body (kept frontend). */
 function stripUseClient(member) {
@@ -137,21 +609,40 @@ function stripUseClient(member) {
 }
 /**
 * The tool's nature, inferred from its (mandatory) `execute` rather than an
-* authored `type`: `hitl()` → `human`; `"use client"` → `frontend`; otherwise
-* `backend`. The loader writes the result back as a `type` field (see
-* {@link setToolType}) so the runtime keeps it.
+* authored `type`: `humanTool()` → `human`; `providerTool(...)` → `provider`;
+* `stubTool()` → `frontend`; `externalTool()` → `backend`; `"use client"` →
+* `frontend`; otherwise `backend`.
+* The loader writes the result back as a `type` field (see {@link setToolType})
+* so the runtime keeps it.
 */
 function inferToolType(object, filename) {
 	const execute = findMember(object, "execute");
-	if (!execute) throw new GenerativeCompileError("every tool must declare an `execute`; use `hitl()` for a human-in-the-loop tool", filename);
-	if (executeIsHitl(execute)) return "human";
+	if (!execute) throw new GenerativeCompileError("every tool must declare an `execute`; use `humanTool()` for a human-in-the-loop tool", filename);
+	if (executeIsHumanTool(execute)) return "human";
+	if (executeIsProviderTool(execute)) return "provider";
+	if (executeIsStubTool(execute)) return "frontend";
+	if (executeIsExternalTool(execute)) return "backend";
 	return executeIsClient(execute) ? "frontend" : "backend";
 }
+function stripExternalToolMetadata(object) {
+	removeMember(object, "description");
+	removeMember(object, "parameters");
+	removeMember(object, "disabled");
+	removeMember(object, "toModelOutput");
+	removeMember(object, "experimental_onSchemaValidationError");
+	removeMember(object, "providerOptions");
+	removeMember(object, "streamCall");
+}
 /** Writes the resolved `type` back onto the tool object (replacing any author's). */
 function setToolType(object, type) {
 	removeMember(object, "type");
 	object.properties.push(t.objectProperty(t.identifier("type"), t.stringLiteral(type)));
 }
+function setBackendDefault(object, target, type) {
+	removeMember(object, "unstable_backendDefault");
+	if (target !== "client" || type !== "frontend" && type !== "human") return;
+	object.properties.push(t.objectProperty(t.identifier("unstable_backendDefault"), t.objectExpression([t.objectProperty(t.identifier("parameters"), t.booleanLiteral(true))])));
+}
 function memberName(key, computed) {
 	if (computed) return void 0;
 	if (t.isIdentifier(key)) return key.name;