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

package/README.md

@@ -8,14 +8,16 @@ colocates a tool's schema, its server-only `execute`, and its client-only
 `render`, and rewrites it for a single build target:
 
 - **client** — keeps `render` and any `"use client"` `execute` (frontend tools),
-  drops backend `execute` and `hitl()` sentinels, and stamps each tool's inferred
-  `type`.
+  drops backend `execute` and `humanTool()` sentinels, and stamps each tool's
+  inferred `type`.
 - **server** — keeps the backend `execute` (importing `server-only`), drops
-  `render`.
+  `render`, and omits externally-defined backend tools marked with
+  `externalTool()`.
 
 The marker functions a `"use generative"` file imports — `defineToolkit` and
-`hitl` — live in `@assistant-ui/core/react` (re-exported from `@assistant-ui/react`).
-This package only recognizes them by name and strips them at build time.
+`humanTool` — live in `@assistant-ui/core/react` (re-exported from
+`@assistant-ui/react`). This package only recognizes them by name and strips them
+at build time.
 
 ## API
 

package/dist/compile.d.ts

@@ -1,7 +1,7 @@
 import { Target } from "./constants.js";
 
 //#region src/compile.d.ts
-type ToolType = "frontend" | "backend" | "human";
+type ToolType = "frontend" | "backend" | "human" | "provider";
 interface CompileOptions {
   /** Which build target to emit. */
   target: Target;

package/dist/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","names":[],"sources":["../src/compile.ts"],"mappings":";;;KAeY,QAAA;AAAA,UAEK,cAAA;EAFL;EAIV,MAAA,EAAQ,MAAM;;EAEd,QAAA;EANkB;EAQlB,UAAA;EAN6B;;;;;;;;EAe7B,gBAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA;EACA,GAAG;AAAA;AAAA;AAAA,cAIQ,sBAAA,SAA+B,KAAK;cACnC,OAAA,UAAiB,QAAA;AAAA;;iBAOf,kBAAA,CAAmB,IAAY;;;;;iBA4B/B,iBAAA,CACd,IAAA,UACA,OAAA,EAAS,cAAA,GACR,aAAa"}
+{"version":3,"file":"compile.d.ts","names":[],"sources":["../src/compile.ts"],"mappings":";;;KAmBY,QAAA;AAAA,UAkCK,cAAA;EAlCL;EAoCV,MAAA,EAAQ,MAAM;;EAEd,QAAA;EAtCkB;EAwClB,UAAA;EAN6B;;;;;;;;EAe7B,gBAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA;EACA,GAAG;AAAA;AAAA;AAAA,cAIQ,sBAAA,SAA+B,KAAK;cACnC,OAAA,UAAiB,QAAA;AAAA;;iBAOf,kBAAA,CAAmB,IAAY;;;;;iBA4B/B,iBAAA,CACd,IAAA,UACA,OAAA,EAAS,cAAA,GACR,aAAa"}

package/dist/compile.js

@@ -1,11 +1,38 @@
 import { DIRECTIVE } from "./constants.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 +72,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);
+	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 +112,268 @@ 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;
+const checkedCorePackageJsonPaths = /* @__PURE__ */ new Set();
+let compilerPackageVersion;
+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;
+	}
+	const compilerVersion = getCompilerPackageVersion();
+	let compatible = false;
+	try {
+		compatible = satisfies(compilerVersion, 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 ${compilerVersion}. Update @assistant-ui/next or @assistant-ui/vite so their compiler satisfies the core package's optionalDevDependencies range.`, filename);
+	checkedCorePackageJsonPaths.add(corePackageJsonPath);
+}
+function getCompilerPackageVersion() {
+	if (compilerPackageVersion) return compilerPackageVersion;
+	const packageJsonPath = findPackageJson(import.meta.url, COMPILER_PACKAGE);
+	const packageJson = packageJsonPath ? readPackageJson(packageJsonPath) : null;
+	if (!packageJson?.version) throw new GenerativeCompileError(`could not determine ${COMPILER_PACKAGE}'s package version`);
+	compilerPackageVersion = packageJson.version;
+	return compilerPackageVersion;
+}
+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) {
+	if (filename) {
+		const cleanFilename = filename.split(/[?#]/, 1)[0];
+		if (nodePath.isAbsolute(cleanFilename)) return cleanFilename;
+	}
+	return import.meta.url;
+}
+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 (!unwrapToCall(def.declaration, TOOLKIT_WRAPPER)) throw new GenerativeCompileError(`the default export must be ${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;
+}
+/**
+* Local toolkit variables whose initializer is visible to this compiler pass
+* are safe to spread. `defineToolkit(...)` initializers are compiled in-place
+* before a later spread reads them; `defineMcpToolkit(...)` entries cannot
+* contain executable code.
+*/
+function collectSafeToolkitSpreads(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) || !init) continue;
+			if (unwrapToToolkitCall(init)) names.add(id.name);
+		}
+	}
+	return names;
+}
+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");
 	}
-	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.
+* 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 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];
+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 +397,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 +423,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;