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

package/src/compile.ts

@@ -1,7 +1,11 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as nodePath from "node:path";
 import { parse } from "@babel/parser";
 import _traverse, { type NodePath } from "@babel/traverse";
 import _generate from "@babel/generator";
 import * as t from "@babel/types";
+import { satisfies } from "semver";
 import { DIRECTIVE, type Target } from "./constants";
 
 // @babel/traverse and @babel/generator are CJS; their default export is the
@@ -13,7 +17,39 @@ const generate = (
   typeof _generate === "function" ? _generate : (_generate as any).default
 ) as typeof _generate;
 
-export type ToolType = "frontend" | "backend" | "human";
+export type ToolType = "frontend" | "backend" | "human" | "provider";
+
+/** 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",
+] as const;
+/**
+ * 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";
+
+/** Mutable per-build outcomes the toolkit pass reports back for directive/guard injection. */
+interface TargetFlags {
+  /** A `render` survived on a client build (→ emit `"use client"`). */
+  keptRender: boolean;
+  /** A backend `execute` survived on a server build (→ emit `import "server-only"`). */
+  keptBackendExecute: boolean;
+}
 
 export interface CompileOptions {
   /** Which build target to emit. */
@@ -93,52 +129,64 @@ export function compileGenerative(
     );
   }
 
-  const object = findDefaultExportObject(ast, filename);
+  ensureCompilerCompatibleWithCore(ast, filename);
 
-  let keptRender = false;
-  let keptBackendExecute = false;
+  // A module may hold several `defineToolkit(...)` / `defineGenerativeComponents(...)`
+  // calls anywhere (e.g. a library built inside `new JSONGenerativeUI(...)` plus
+  // the toolkit that exposes it). Tools may reference a `JSONGenerativeUI`
+  // instance's `present()`/`promptUser()`, which the library — not this compiler —
+  // splits across builds via export conditions; collect those instance names so
+  // such entries pass through.
+  ensureDefaultExport(ast, filename);
+  const generativeInstances = collectGenerativeInstances(ast);
+  const safeToolkitSpreads = collectSafeToolkitSpreads(ast);
 
-  for (const entry of object.properties) {
-    const value = entryValue(entry);
-    if (!value) {
-      // A non-inline tool (spread, method, or a call like `makeTool()`) can't be
-      // analyzed, so its `execute` would pass through to the client unstripped.
-      throw new GenerativeCompileError(
-        "each tool must be an inline object literal (`name: { ... }`) so its " +
-          "`execute` can be routed",
-        filename,
-      );
-    }
+  const flags: TargetFlags = { keptRender: false, keptBackendExecute: false };
 
-    // Nature is inferred from `execute` (see inferToolType), not an authored
-    // `type`. The resolved type is written back below so the runtime keeps it.
-    const type = inferToolType(value, filename);
-    const hasRender = !!findMember(value, "render");
-    const execute = findMember(value, "execute");
+  traverse(ast, {
+    CallExpression(path: NodePath<t.CallExpression>) {
+      const callee = path.node.callee;
+      const object = t.isObjectExpression(path.node.arguments[0])
+        ? path.node.arguments[0]
+        : null;
 
-    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 (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);
+        // Unwrap the authoring helper to the bare library object so its import
+        // can be pruned.
+        path.replaceWith(object);
+        path.skip();
+        return;
+      }
 
-    if (target === "client") {
-      // A frontend execute stays (its `"use client"` marker is no longer needed
-      // once the module is client); a backend execute and a human `hitl()`
-      // sentinel are both dropped.
-      if (execute && type === "frontend") stripUseClient(execute);
-      else if (execute) removeMember(value, "execute");
-      if (hasRender) keptRender = true;
-    } else {
-      // server: render is never needed; only a backend execute survives.
-      if (hasRender) removeMember(value, "render");
-      if (execute && type !== "backend") removeMember(value, "execute");
-      if (execute && type === "backend") keptBackendExecute = true;
-    }
+      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();
+      }
+    },
+  });
 
-    setToolType(value, type);
-  }
+  const { keptRender, keptBackendExecute } = flags;
 
   pruneUnused(ast);
 
@@ -174,61 +222,543 @@ export function compileGenerative(
   return { code: result.code, map: result.map };
 }
 
-function findDefaultExportObject(
+interface PackageJson {
+  name?: string;
+  version?: string;
+  optionalDevDependencies?: Record<string, string>;
+}
+
+const checkedCorePackageJsonPaths = new Set<string>();
+let compilerPackageVersion: string | undefined;
+
+function ensureCompilerCompatibleWithCore(
   ast: t.File,
   filename: string | undefined,
-): t.ObjectExpression {
-  let object: t.ObjectExpression | null = null;
-  let sawDefault = false;
+): void {
+  const corePackageJsonPath = resolveCorePackageJson(ast, filename);
+  if (
+    !corePackageJsonPath ||
+    checkedCorePackageJsonPaths.has(corePackageJsonPath)
+  ) {
+    return;
+  }
 
-  for (const stmt of ast.program.body) {
-    if (!t.isExportDefaultDeclaration(stmt)) continue;
-    sawDefault = true;
-    object = unwrapDefineToolkit(stmt.declaration);
-    // Emit the bare object literal, dropping the `defineToolkit(...)` wrapper
-    // (and the import it pulled).
-    if (object) stmt.declaration = object;
+  const corePackageJson = readPackageJson(corePackageJsonPath);
+  const range = corePackageJson?.optionalDevDependencies?.[COMPILER_PACKAGE];
+  if (!range) {
+    checkedCorePackageJsonPaths.add(corePackageJsonPath);
+    return;
   }
 
-  if (!sawDefault) {
+  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(): string {
+  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: t.File,
+  filename: string | undefined,
+): string | null {
+  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: t.File): Set<string> {
+  const packages = new Set<string>();
+
+  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: string): string | null {
+  for (const packageName of DISTRIBUTION_PACKAGES) {
+    if (specifier === packageName || specifier.startsWith(`${packageName}/`)) {
+      return packageName;
+    }
+  }
+
+  return null;
+}
+
+function resolvePackageJson(
+  packageName: string,
+  filename: string | undefined,
+): string | null {
+  const requirePath = normalizeRequirePath(filename);
+  const require = createRequire(requirePath);
+
+  try {
+    return findPackageJson(require.resolve(packageName), packageName);
+  } catch {
+    return findPackageJsonFromNodeModules(packageName, requirePath);
+  }
+}
+
+function normalizeRequirePath(filename: string | undefined): string {
+  if (filename) {
+    const cleanFilename = filename.split(/[?#]/, 1)[0]!;
+    if (nodePath.isAbsolute(cleanFilename)) return cleanFilename;
+  }
+  return import.meta.url;
+}
+
+function findPackageJson(
+  fromPathOrUrl: string,
+  packageName: string,
+): string | null {
+  let current = nodePath.dirname(
+    fromPathOrUrl.startsWith("file:")
+      ? new URL(fromPathOrUrl).pathname
+      : nodePath.resolve(fromPathOrUrl),
+  );
+
+  for (;;) {
+    const packageJsonPath = nodePath.join(current, "package.json");
+    const packageJson = readPackageJson(packageJsonPath);
+    if (packageJson?.name === packageName) return packageJsonPath;
+
+    const parent = nodePath.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function findPackageJsonFromNodeModules(
+  packageName: string,
+  fromPathOrUrl: string,
+): string | null {
+  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",
+    );
+    const packageJson = readPackageJson(packageJsonPath);
+    if (packageJson?.name === packageName) return packageJsonPath;
+
+    const parent = nodePath.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function readPackageJson(packageJsonPath: string): PackageJson | null {
+  if (!existsSync(packageJsonPath)) return null;
+  try {
+    return JSON.parse(readFileSync(packageJsonPath, "utf8")) as PackageJson;
+  } 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: t.File, filename: string | undefined): void {
+  const def = ast.program.body.find(
+    (stmt): stmt is t.ExportDefaultDeclaration =>
+      t.isExportDefaultDeclaration(stmt),
+  );
+  if (!def) {
     throw new GenerativeCompileError("missing a default export", filename);
   }
-  if (!object) {
+  if (!unwrapToCall(def.declaration, TOOLKIT_WRAPPER)) {
     throw new GenerativeCompileError(
-      "the default export must be `defineToolkit({ ... })` (imported from " +
+      `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,
     );
   }
-  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.
+ * Unwraps a node through `satisfies`/`as`/parens to a call of the named function,
+ * or returns `null`.
  */
-function unwrapDefineToolkit(node: t.Node): t.ObjectExpression | null {
+function unwrapToCall(node: t.Node, name: string): t.CallExpression | null {
   if (t.isTSSatisfiesExpression(node) || t.isTSAsExpression(node)) {
-    return unwrapDefineToolkit(node.expression);
+    return unwrapToCall(node.expression, name);
   }
   if (t.isParenthesizedExpression(node)) {
-    return unwrapDefineToolkit(node.expression);
+    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: t.File): Set<string> {
+  const names = new Set<string>();
+  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: t.File): Set<string> {
+  const names = new Set<string>();
+  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: t.Node): t.CallExpression | null {
+  return (
+    unwrapToCall(node, TOOLKIT_WRAPPER) ??
+    unwrapToCall(node, MCP_TOOLKIT_WRAPPER)
+  );
+}
+
+function isSafeToolkitSpread(
+  entry: t.SpreadElement,
+  safeToolkitSpreads: Set<string>,
+): boolean {
+  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: t.Node, instances: Set<string>): boolean {
+  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: t.ObjectExpression,
+  target: Target,
+  flags: TargetFlags,
+  filename: string | undefined,
+): void {
+  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;
+    // The client keeps `render` (and so needs the module marked `"use client"`);
+    // the server drops it, since only the schema reaches the model there.
+    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: t.ObjectExpression,
+  target: Target,
+  instances: Set<string>,
+  safeToolkitSpreads: Set<string>,
+  flags: TargetFlags,
+  filename: string | undefined,
+): void {
+  const nextProperties: t.ObjectExpression["properties"] = [];
+
+  for (const entry of object.properties) {
+    const value = entryValue(entry);
+    if (!value) {
+      if (
+        t.isSpreadElement(entry) &&
+        isSafeToolkitSpread(entry, safeToolkitSpreads)
+      ) {
+        nextProperties.push(entry);
+        continue;
+      }
+      // A generative tool (`generative.present()`) is split by the library's
+      // export conditions, so it is safe to keep verbatim. Anything else — a
+      // method or opaque call like `makeTool()` — can't be analyzed, so its
+      // `execute` could reach the client unstripped.
+      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,
+      );
+    }
+
+    // Nature is inferred from `execute` (see inferToolType), not an authored
+    // `type`. The resolved type is written back below so the runtime keeps it.
+    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") {
+      // A non-stub frontend execute stays (its `"use client"` marker is no longer needed
+      // once the module is client); backend, sentinel, and stub executes are dropped.
+      if (execute && type === "frontend" && !isStub) stripUseClient(execute);
+      else if (execute) removeMember(value, "execute");
+      if (hasRender || hasRenderText) flags.keptRender = true;
+    } else {
+      // server: render is never needed; only a non-external backend execute survives.
+      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: t.ObjectExpression,
+  execute: t.ObjectProperty | t.ObjectMethod,
+  filename: string | undefined,
+): void {
   if (
-    t.isCallExpression(node) &&
-    t.isIdentifier(node.callee, { name: "defineToolkit" }) &&
-    t.isObjectExpression(node.arguments[0])
+    !t.isObjectProperty(execute) ||
+    !t.isCallExpression(execute.value) ||
+    execute.value.arguments.length !== 1 ||
+    !t.isObjectExpression(execute.value.arguments[0])
   ) {
-    return node.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 = new Set<string>();
+
+  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);
   }
-  return null;
 }
 
 type Entry = t.ObjectExpression["properties"][number];
 
+/** The raw AST value of an entry (any expression), or null for spreads/methods. */
+function entryRawValue(entry: Entry): t.Expression | null {
+  if (t.isObjectProperty(entry) && t.isExpression(entry.value)) {
+    return entry.value;
+  }
+  return null;
+}
+
 function entryValue(entry: Entry): t.ObjectExpression | null {
   if (t.isObjectProperty(entry) && t.isObjectExpression(entry.value)) {
     return entry.value;
@@ -280,15 +810,47 @@ function executeIsClient(member: t.ObjectProperty | t.ObjectMethod): boolean {
   );
 }
 
-/** Whether an `execute` is the `hitl()` human-in-the-loop sentinel. */
-function executeIsHitl(member: t.ObjectProperty | t.ObjectMethod): boolean {
+function executeIsSentinel(
+  member: t.ObjectProperty | t.ObjectMethod,
+  name: string,
+): boolean {
   return (
     t.isObjectProperty(member) &&
     t.isCallExpression(member.value) &&
-    t.isIdentifier(member.value.callee, { name: "hitl" })
+    t.isIdentifier(member.value.callee, { name })
+  );
+}
+
+/** Whether an `execute` is the human-in-the-loop sentinel. */
+function executeIsHumanTool(
+  member: t.ObjectProperty | t.ObjectMethod,
+): boolean {
+  return (
+    executeIsSentinel(member, "humanTool") ||
+    executeIsSentinel(member, "hitlTool") ||
+    executeIsSentinel(member, "hitl")
   );
 }
 
+/** Whether an `execute` is the provider-tool sentinel. */
+function executeIsProviderTool(
+  member: t.ObjectProperty | t.ObjectMethod,
+): boolean {
+  return executeIsSentinel(member, "providerTool");
+}
+
+/** Whether an `execute` is the local override sentinel. */
+function executeIsStubTool(member: t.ObjectProperty | t.ObjectMethod): boolean {
+  return executeIsSentinel(member, "stubTool");
+}
+
+/** Whether an `execute` is the externally-defined backend tool sentinel. */
+function executeIsExternalTool(
+  member: t.ObjectProperty | t.ObjectMethod,
+): boolean {
+  return executeIsSentinel(member, "externalTool");
+}
+
 /** Drops the `"use client"` directive from an `execute` body (kept frontend). */
 function stripUseClient(member: t.ObjectProperty | t.ObjectMethod): void {
   const body = executeBody(member);
@@ -301,9 +863,11 @@ function stripUseClient(member: t.ObjectProperty | t.ObjectMethod): void {
 
 /**
  * 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: t.ObjectExpression,
@@ -312,15 +876,31 @@ function inferToolType(
   const execute = findMember(object, "execute");
   if (!execute) {
     throw new GenerativeCompileError(
-      "every tool must declare an `execute`; use `hitl()` for a " +
+      "every tool must declare an `execute`; use `humanTool()` for a " +
         "human-in-the-loop tool",
       filename,
     );
   }
-  if (executeIsHitl(execute)) return "human";
+  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: t.ObjectExpression): void {
+  // Mirror BackendTool's forbidden metadata fields: execute is stripped by the
+  // main routing loop, while streamCall is also removed because there is no
+  // assistant-ui executor to stream from.
+  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: t.ObjectExpression, type: ToolType): void {
   removeMember(object, "type");
@@ -330,6 +910,26 @@ function setToolType(object: t.ObjectExpression, type: ToolType): void {
   );
 }
 
+function setBackendDefault(
+  object: t.ObjectExpression,
+  target: Target,
+  type: ToolType,
+): void {
+  // Always strip any hand-authored marker first; only re-add it for client
+  // frontend/human tools whose schema is already known by the backend.
+  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: t.Node,
   computed: boolean | undefined,