@assistant-ui/x-generative-compiler 0.0.5 → 0.0.8

package/dist/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","names":[],"sources":["../src/compile.ts"],"mappings":";;;KAoBY,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"}
+{"version":3,"file":"compile.d.ts","names":[],"sources":["../src/compile.ts"],"mappings":";;;KAoBY,QAAA;AAAA,UA2CK,cAAA;EA3CL;EA6CV,MAAA,EAAQ,MAAM;;EAEd,QAAA;EA/CkB;EAiDlB,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;;iBASf,kBAAA,CAAmB,IAAY;;;;;iBA+I/B,iBAAA,CACd,IAAA,UACA,OAAA,EAAS,cAAA,GACR,aAAa"}

package/dist/compile.js

@@ -28,16 +28,25 @@ const DISTRIBUTION_PACKAGES = [
 	"@assistant-ui/react-native",
 	"@assistant-ui/react-ink"
 ];
+/** Package that exports the generative UI runtime split by export condition. */
+const GENERATIVE_UI_PACKAGE = "@assistant-ui/react-generative-ui";
 /**
 * 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";
+/**
+* The factory producing an interactable's complete tool entry. Unlike
+* `JSONGenerativeUI`, its package has no per-target builds, so this compiler
+* splits the inline config: the client keeps `render`, the server drops it.
+* The factory's own `execute` is internal and client-safe (frontend tool).
+*/
+const INTERACTABLE_TOOL_FACTORY = "unstable_interactableTool";
 /** Thrown when a `"use generative"` file violates an authoring constraint. */
 var GenerativeCompileError = class extends Error {
 	constructor(message, filename) {
-		super(`[assistant-ui/next]${filename ? ` ${filename}:` : ""} ${message}`);
+		super(`[assistant-ui/use-generative]${filename ? ` ${filename}:` : ""} ${message}`);
 		this.name = "GenerativeCompileError";
 	}
 };
@@ -56,7 +65,89 @@ function isGenerativeModule(code) {
 			i = end + 2;
 		} else break;
 	}
-	return code.startsWith(`"use generative"`, i) || code.startsWith(`'use generative'`, i);
+	const quote = code[i];
+	if (quote !== "\"" && quote !== "'") return false;
+	const directiveStart = i + 1;
+	if (!code.startsWith("use generative", directiveStart)) return false;
+	const directiveEnd = directiveStart + DIRECTIVE.length;
+	if (code[directiveEnd] !== quote) return false;
+	return hasDirectiveTerminator(code, directiveEnd + 1);
+}
+function hasDirectiveTerminator(code, start) {
+	let i = start;
+	let sawLineTerminator = false;
+	for (;;) {
+		if (i >= code.length) return true;
+		const char = code.charCodeAt(i);
+		if (isSemicolon(char)) return true;
+		if (isLineTerminator(char)) {
+			sawLineTerminator = true;
+			i++;
+			continue;
+		}
+		if (code.startsWith("//", i)) {
+			const lineEnd = nextLineTerminatorIndex(code, i + 2);
+			if (lineEnd === -1) return true;
+			sawLineTerminator = true;
+			i = lineEnd + 1;
+			continue;
+		}
+		if (code.startsWith("/*", i)) {
+			const end = code.indexOf("*/", i + 2);
+			if (end === -1) return false;
+			sawLineTerminator ||= containsLineTerminator(code, i + 2, end);
+			i = end + 2;
+			continue;
+		}
+		if (/\s/.test(code[i])) {
+			i++;
+			continue;
+		}
+		return sawLineTerminator && !startsExpressionContinuation(code, i);
+	}
+}
+function nextLineTerminatorIndex(code, start) {
+	for (let i = start; i < code.length; i++) if (isLineTerminator(code.charCodeAt(i))) return i;
+	return -1;
+}
+function containsLineTerminator(code, start, end) {
+	for (let i = start; i < end; i++) if (isLineTerminator(code.charCodeAt(i))) return true;
+	return false;
+}
+function startsExpressionContinuation(code, start) {
+	switch (code[start]) {
+		case ".":
+		case "+":
+		case "-":
+		case "*":
+		case "/":
+		case "%":
+		case "<":
+		case ">":
+		case "=":
+		case "!":
+		case "&":
+		case "|":
+		case "^":
+		case "?":
+		case ":":
+		case ",":
+		case "[":
+		case "(":
+		case "`": return true;
+	}
+	return startsKeywordContinuation(code, start, "as") || startsKeywordContinuation(code, start, "in") || startsKeywordContinuation(code, start, "instanceof") || startsKeywordContinuation(code, start, "satisfies");
+}
+function startsKeywordContinuation(code, start, keyword) {
+	if (!code.startsWith(keyword, start)) return false;
+	const next = code[start + keyword.length];
+	return next === void 0 || !/[\p{ID_Continue}$]/u.test(next);
+}
+function isSemicolon(char) {
+	return char === 59;
+}
+function isLineTerminator(char) {
+	return char === 10 || char === 13 || char === 8232 || char === 8233;
 }
 /**
 * Rewrites a `"use generative"` module for a single build target, keeping only the
@@ -76,7 +167,8 @@ function compileGenerative(code, options) {
 	ensureCompilerCompatibleWithCore(ast, filename);
 	ensureDefaultExport(ast, filename);
 	const generativeInstances = collectGenerativeInstances(ast);
-	const safeToolkitSpreads = collectSafeToolkitSpreads(ast, filename);
+	const interactableToolImports = collectInteractableToolImports(ast);
+	const toolkitSpreadNames = collectToolkitSpreadNames(ast, filename, createToolkitNameContext());
 	const flags = {
 		keptRender: false,
 		keptBackendExecute: false
@@ -93,7 +185,7 @@ function compileGenerative(code, options) {
 		}
 		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);
+			compileToolkit(object, target, generativeInstances, interactableToolImports, toolkitSpreadNames, flags, filename);
 			path.replaceWith(object);
 			path.skip();
 		}
@@ -234,17 +326,56 @@ function unwrapToCall(node, name) {
 */
 function collectGenerativeInstances(ast) {
 	const names = /* @__PURE__ */ new Set();
+	const generativeFactories = collectGenerativeFactoryImports(ast);
 	for (const statement of ast.program.body) {
-		if (!t.isVariableDeclaration(statement)) continue;
-		for (const declaration of statement.declarations) {
+		const variableDeclaration = t.isVariableDeclaration(statement) ? statement : t.isExportNamedDeclaration(statement) && t.isVariableDeclaration(statement.declaration) ? statement.declaration : null;
+		if (!variableDeclaration) continue;
+		for (const declaration of variableDeclaration.declarations) {
 			const { id, init } = declaration;
-			if (t.isIdentifier(id) && t.isNewExpression(init) && t.isIdentifier(init.callee, { name: GENERATIVE_FACTORY })) names.add(id.name);
+			if (t.isIdentifier(id) && t.isNewExpression(init) && t.isIdentifier(init.callee) && generativeFactories.has(init.callee.name)) names.add(id.name);
 		}
 	}
 	return names;
 }
+function collectGenerativeFactoryImports(ast) {
+	const names = /* @__PURE__ */ new Set();
+	for (const statement of ast.program.body) {
+		if (!t.isImportDeclaration(statement) || statement.source.value !== GENERATIVE_UI_PACKAGE) continue;
+		for (const specifier of statement.specifiers) if (t.isImportSpecifier(specifier) && t.isIdentifier(specifier.imported, { name: GENERATIVE_FACTORY })) names.add(specifier.local.name);
+	}
+	return names;
+}
+/**
+* Collects the local names `unstable_interactableTool` is imported under from a
+* distribution package, so toolkit entries calling it can be recognized
+* (and a same-named local function can't smuggle an arbitrary call through).
+*/
+function collectInteractableToolImports(ast) {
+	const names = /* @__PURE__ */ new Set();
+	for (const statement of ast.program.body) {
+		if (!t.isImportDeclaration(statement)) continue;
+		if (!packageNameFromSpecifier(statement.source.value)) continue;
+		for (const specifier of statement.specifiers) if (t.isImportSpecifier(specifier) && t.isIdentifier(specifier.imported, { name: INTERACTABLE_TOOL_FACTORY })) names.add(specifier.local.name);
+	}
+	return names;
+}
+function createToolkitNameContext() {
+	return {
+		importedToolkitNamesByFile: /* @__PURE__ */ new Map(),
+		resolvingImportedToolkitNames: /* @__PURE__ */ new Set()
+	};
+}
 /**
-* Toolkit identifiers that are safe to spread into a `defineToolkit({ ... })`.
+* The inline config of an `unstable_interactableTool({ ... })` toolkit entry, or `null`
+* when the entry is some other expression.
+*/
+function interactableToolConfig(value, imports) {
+	return t.isCallExpression(value) && t.isIdentifier(value.callee) && imports.has(value.callee.name) && t.isObjectExpression(value.arguments[0]) ? value.arguments[0] : null;
+}
+/**
+* Toolkit identifiers that are safe to spread into a `defineToolkit({ ... })`,
+* paired with the static tool names they contain. A `null` name list means the
+* spread is safe, but its names are not statically known for duplicate checks.
 *
 * Two kinds qualify:
 *
@@ -257,30 +388,38 @@ function collectGenerativeInstances(ast) {
 *   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();
+function collectToolkitSpreadNames(ast, filename, context) {
+	const spreadNames = /* @__PURE__ */ new Map();
+	const localToolkitCalls = /* @__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);
+				if (t.isIdentifier(id) && init) {
+					const toolkitCall = unwrapToToolkitCall(init);
+					if (toolkitCall) localToolkitCalls.set(id.name, toolkitCall);
+				}
 			}
 			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);
+			const names = getGenerativeImportToolkitNames(statement.source.value, filename, context);
+			if (names !== void 0) spreadNames.set(defaultSpecifier.local.name, names);
 		}
 	}
-	return names;
+	const resolveLocal = (name) => {
+		if (spreadNames.has(name)) return spreadNames.get(name);
+		const call = localToolkitCalls.get(name);
+		if (!call) return void 0;
+		const object = t.isObjectExpression(call.arguments[0]) ? call.arguments[0] : null;
+		const publicNames = uniqueToolkitNames(object ? collectToolkitObjectNames(object, spreadNames) : null);
+		spreadNames.set(name, publicNames);
+		return publicNames;
+	};
+	for (const name of localToolkitCalls.keys()) resolveLocal(name);
+	return spreadNames;
 }
 const MODULE_EXTENSIONS = [
 	".ts",
@@ -293,29 +432,64 @@ const MODULE_EXTENSIONS = [
 	".cjs"
 ];
 /** Extensions a specifier may carry that actually map to a TS source file. */
-const REWRITABLE_JS_EXTENSIONS = new Set([
+const REWRITABLE_JS_EXTENSIONS = /* @__PURE__ */ 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.
+* Reads the static tool names from the default export of an imported
+* `"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) {
+function getGenerativeImportToolkitNames(source, filename, context) {
 	const cleanFilename = cleanAbsoluteFilename(filename);
-	if (!cleanFilename) return false;
+	if (!cleanFilename) return void 0;
 	const resolved = resolveImportedModuleFile(source, cleanFilename);
-	if (!resolved) return false;
+	if (!resolved) return void 0;
+	if (context.importedToolkitNamesByFile.has(resolved)) return context.importedToolkitNamesByFile.get(resolved);
+	if (context.resolvingImportedToolkitNames.has(resolved)) return null;
+	let code;
 	try {
-		return isGenerativeModule(readFileSync(resolved, "utf8"));
+		code = readFileSync(resolved, "utf8");
 	} catch {
-		return false;
+		context.importedToolkitNamesByFile.set(resolved, void 0);
+		return;
+	}
+	if (!isGenerativeModule(code)) {
+		context.importedToolkitNamesByFile.set(resolved, void 0);
+		return;
+	}
+	context.resolvingImportedToolkitNames.add(resolved);
+	try {
+		const names = getDefaultExportToolkitNames(parse(code, {
+			sourceType: "module",
+			plugins: [
+				"typescript",
+				"jsx",
+				"explicitResourceManagement"
+			]
+		}), resolved, context);
+		context.importedToolkitNamesByFile.set(resolved, names);
+		return names;
+	} catch (error) {
+		if (error instanceof GenerativeCompileError) throw error;
+		context.importedToolkitNamesByFile.set(resolved, null);
+		return null;
+	} finally {
+		context.resolvingImportedToolkitNames.delete(resolved);
 	}
 }
+function getDefaultExportToolkitNames(ast, filename, context) {
+	const def = ast.program.body.find((stmt) => t.isExportDefaultDeclaration(stmt));
+	if (!def) return null;
+	const toolkitCall = unwrapToToolkitCall(def.declaration);
+	if (!toolkitCall || !t.isObjectExpression(toolkitCall.arguments[0])) return null;
+	const spreadNames = collectToolkitSpreadNames(ast, filename, context);
+	return uniqueToolkitNames(collectToolkitObjectNames(toolkitCall.arguments[0], spreadNames));
+}
 /** 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));
@@ -456,13 +630,64 @@ function parseJsonc(text) {
 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);
+function collectToolkitObjectNames(object, toolkitSpreadNames) {
+	const names = [];
+	for (const entry of object.properties) {
+		const entryNames = toolkitEntryNames(entry, toolkitSpreadNames);
+		if (!entryNames) return null;
+		names.push(...entryNames);
+	}
+	return names;
+}
+function uniqueToolkitNames(names) {
+	return names ? [...new Set(names)] : names;
+}
+function toolkitEntryNames(entry, toolkitSpreadNames) {
+	if (t.isSpreadElement(entry)) {
+		if (t.isIdentifier(entry.argument)) return toolkitSpreadNames.get(entry.argument.name) ?? null;
+		const directMcpToolkit = unwrapToCall(entry.argument, MCP_TOOLKIT_WRAPPER);
+		if (directMcpToolkit && t.isObjectExpression(directMcpToolkit.arguments[0])) return collectToolkitObjectNames(directMcpToolkit.arguments[0], toolkitSpreadNames);
+		return null;
+	}
+	if (t.isObjectProperty(entry) || t.isObjectMethod(entry)) {
+		const name = memberName(entry.key, entry.computed);
+		return name ? [name] : [];
+	}
+	return [];
+}
+function warnDuplicateToolkitNames(object, toolkitSpreadNames, filename) {
+	const names = collectToolkitObjectNames(object, toolkitSpreadNames);
+	if (!names) return;
+	const seen = /* @__PURE__ */ new Set();
+	const warned = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		if (seen.has(name)) {
+			if (!warned.has(name)) {
+				console.warn(new GenerativeCompileError(`Duplicate tool name "${name}" while composing toolkits. JavaScript object spread keeps the last definition.`, filename).message);
+				warned.add(name);
+			}
+			continue;
+		}
+		seen.add(name);
+	}
+}
+function isSafeToolkitSpread(entry, toolkitSpreadNames) {
+	if (t.isIdentifier(entry.argument)) return toolkitSpreadNames.has(entry.argument.name);
 	const directMcpToolkit = unwrapToCall(entry.argument, MCP_TOOLKIT_WRAPPER);
 	return !!directMcpToolkit && t.isObjectExpression(directMcpToolkit.arguments[0]);
 }
+function genericUnsafeToolkitEntryMessage() {
+	return "each tool must be an inline object literal (`name: { ... }`) or a compiler-visible toolkit spread / generative tool (e.g. `...defineMcpToolkit(...)`, `...baseToolkit`, `generative.present()`, or `unstable_interactableTool(...)`) so its `execute` can be routed";
+}
+function describeUnsafeToolkitEntry(entry) {
+	if (!t.isObjectProperty(entry)) return genericUnsafeToolkitEntryMessage();
+	const toolName = memberName(entry.key, entry.computed);
+	const raw = entryRawValue(entry);
+	if (!toolName || !raw) return genericUnsafeToolkitEntryMessage();
+	return `tool "${toolName}" cannot be \`${generate(raw).code}\`; use an inline object literal (\`${toolName}: { ... }\`) or a compiler-visible toolkit spread / generative tool so its \`execute\` can be routed`;
+}
 /** The `JSONGenerativeUI` methods that produce a split-by-condition tool. */
-const GENERATIVE_TOOL_METHODS = new Set(["present", "promptUser"]);
+const GENERATIVE_TOOL_METHODS = /* @__PURE__ */ 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
@@ -493,12 +718,13 @@ function compileComponents(object, target, flags, filename) {
 * `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) {
+function compileToolkit(object, target, instances, interactableToolImports, toolkitSpreadNames, flags, filename) {
+	if (target === "client") warnDuplicateToolkitNames(object, toolkitSpreadNames, filename);
 	const nextProperties = [];
 	for (const entry of object.properties) {
 		const value = entryValue(entry);
 		if (!value) {
-			if (t.isSpreadElement(entry) && isSafeToolkitSpread(entry, safeToolkitSpreads)) {
+			if (t.isSpreadElement(entry) && isSafeToolkitSpread(entry, toolkitSpreadNames)) {
 				nextProperties.push(entry);
 				continue;
 			}
@@ -507,19 +733,27 @@ function compileToolkit(object, target, instances, safeToolkitSpreads, flags, fi
 				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 config = raw && interactableToolConfig(raw, interactableToolImports);
+			if (config) {
+				if (target === "client") flags.keptRender = true;
+				else removeMember(config, "render");
+				nextProperties.push(entry);
+				continue;
+			}
+			throw new GenerativeCompileError(describeUnsafeToolkitEntry(entry), filename);
 		}
+		const toolName = t.isObjectProperty(entry) ? memberName(entry.key, entry.computed) : void 0;
 		const execute = findMember(value, "execute");
 		const isStub = execute ? executeIsStubTool(execute) : false;
 		const isExternal = execute ? executeIsExternalTool(execute) : false;
-		const type = inferToolType(value, filename);
+		const type = inferToolType(value, toolName, 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 (type === "frontend" && !hasRender && !hasRenderText) throw new GenerativeCompileError(`${typedToolSubject("frontend", toolName)} must declare a \`render\` or \`renderText\` (it has no server execute to show otherwise)`, filename);
+		if (type === "human" && !hasRender) throw new GenerativeCompileError(`${typedToolSubject("human", toolName)} must declare a \`render\` so it can collect input`, filename);
+		if (type === "provider" && execute) applyProviderToolConfig(value, execute, toolName, 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 (!hasRender && !hasRenderText) throw new GenerativeCompileError(`${typedToolSubject("external", toolName)} must declare a \`render\` or \`renderText\` (assistant-ui only renders calls for tools defined elsewhere)`, filename);
 			if (target === "server") continue;
 			stripExternalToolMetadata(value);
 		}
@@ -539,7 +773,7 @@ function compileToolkit(object, target, instances, safeToolkitSpreads, flags, fi
 	}
 	object.properties = nextProperties;
 }
-function applyProviderToolConfig(object, execute, filename) {
+function applyProviderToolConfig(object, execute, toolName, 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 [];
@@ -552,7 +786,7 @@ function applyProviderToolConfig(object, execute, 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);
+		if (existingNames.has(name) || configNames.has(name)) throw new GenerativeCompileError(`\`providerTool(...)\` config${toolName ? ` for "${toolName}"` : ""} duplicates "${name}"`, filename);
 		configNames.add(name);
 		object.properties.push(prop);
 	}
@@ -615,15 +849,22 @@ function stripUseClient(member) {
 * The loader writes the result back as a `type` field (see {@link setToolType})
 * so the runtime keeps it.
 */
-function inferToolType(object, filename) {
+function inferToolType(object, toolName, filename) {
 	const execute = findMember(object, "execute");
-	if (!execute) throw new GenerativeCompileError("every tool must declare an `execute`; use `humanTool()` for a human-in-the-loop tool", filename);
+	if (!execute) throw new GenerativeCompileError(`${toolSubject(toolName)} 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 toolSubject(toolName) {
+	return toolName ? `tool "${toolName}"` : "every tool";
+}
+function typedToolSubject(type, toolName) {
+	if (toolName) return `${type} tool "${toolName}"`;
+	return `${/^[aeiou]/i.test(type) ? "an" : "a"} ${type} tool`;
+}
 function stripExternalToolMetadata(object) {
 	removeMember(object, "description");
 	removeMember(object, "parameters");