@assistant-ui/x-generative-compiler 0.0.1

package/README.md

@@ -0,0 +1,38 @@
+# @assistant-ui/x-generative-compiler
+
+> **Internal package.** Not meant for direct use. Use a build integration such as
+> [`@assistant-ui/next`](../next) or [`@assistant-ui/vite`](../vite).
+
+The framework-agnostic `"use generative"` compiler. It takes a module that
+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`.
+- **server** — keeps the backend `execute` (importing `server-only`), drops
+  `render`.
+
+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.
+
+## API
+
+```ts
+import {
+  compileGenerative,
+  isGenerativeModule,
+  GenerativeCompileError,
+  DIRECTIVE,
+  type Target,
+} from "@assistant-ui/x-generative-compiler";
+
+if (isGenerativeModule(code)) {
+  const { code: out, map } = compileGenerative(code, {
+    target: "server", // or "client"
+    filename,
+    sourceMaps: true,
+  });
+}
+```

package/dist/compile.d.ts

@@ -0,0 +1,39 @@
+import { Target } from "./constants.js";
+
+//#region src/compile.d.ts
+type ToolType = "frontend" | "backend" | "human";
+interface CompileOptions {
+  /** Which build target to emit. */
+  target: Target;
+  /** Source filename, used for error messages and source maps. */
+  filename?: string;
+  /** Emit a source map alongside the code. */
+  sourceMaps?: boolean;
+  /**
+   * Whether the `server` target prepends `import "server-only"` when it keeps a
+   * backend `execute`. Defaults to `true` (the Next.js/RSC convention, where the
+   * guard fires via the `react-server` condition). Set `false` for bundlers
+   * without a `react-server` layer (e.g. a Vite/TanStack Start `ssr` build),
+   * where the split is already structural and importing `server-only` would
+   * throw — see the Vite integration.
+   */
+  injectServerOnly?: boolean;
+}
+interface CompileResult {
+  code: string;
+  map?: object | null;
+}
+/** Thrown when a `"use generative"` file violates an authoring constraint. */
+declare class GenerativeCompileError extends Error {
+  constructor(message: string, filename?: string);
+}
+/** Whether a source string opts into generative compilation via the directive. */
+declare function isGenerativeModule(code: string): boolean;
+/**
+ * Rewrites a `"use generative"` module for a single build target, keeping only the
+ * regions that target needs and pruning the imports the dropped regions used.
+ */
+declare function compileGenerative(code: string, options: CompileOptions): CompileResult;
+//#endregion
+export { CompileOptions, CompileResult, GenerativeCompileError, ToolType, compileGenerative, isGenerativeModule };
+//# sourceMappingURL=compile.d.ts.map

package/dist/compile.d.ts.map

@@ -0,0 +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"}

package/dist/compile.js

@@ -0,0 +1,235 @@
+import { DIRECTIVE } from "./constants.js";
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+import _generate from "@babel/generator";
+import * as t from "@babel/types";
+//#region src/compile.ts
+const traverse = typeof _traverse === "function" ? _traverse : _traverse.default;
+const generate = typeof _generate === "function" ? _generate : _generate.default;
+/** 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}`);
+		this.name = "GenerativeCompileError";
+	}
+};
+/** Whether a source string opts into generative compilation via the directive. */
+function isGenerativeModule(code) {
+	let i = code.charCodeAt(0) === 65279 ? 1 : 0;
+	for (;;) {
+		while (i < code.length && /\s/.test(code[i])) i++;
+		if (code.startsWith("//", i)) {
+			const nl = code.indexOf("\n", i);
+			if (nl === -1) return false;
+			i = nl + 1;
+		} else if (code.startsWith("/*", i)) {
+			const end = code.indexOf("*/", i + 2);
+			if (end === -1) return false;
+			i = end + 2;
+		} else break;
+	}
+	return code.startsWith(`"use generative"`, i) || code.startsWith(`'use generative'`, i);
+}
+/**
+* Rewrites a `"use generative"` module for a single build target, keeping only the
+* regions that target needs and pruning the imports the dropped regions used.
+*/
+function compileGenerative(code, options) {
+	const { target, filename } = options;
+	const ast = parse(code, {
+		sourceType: "module",
+		plugins: [
+			"typescript",
+			"jsx",
+			"explicitResourceManagement"
+		]
+	});
+	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;
+		}
+		setToolType(value, type);
+	}
+	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")));
+	if (target === "server" && keptBackendExecute && (options.injectServerOnly ?? true)) ast.program.body.unshift(t.importDeclaration([], t.stringLiteral("server-only")));
+	const result = generate(ast, {
+		sourceMaps: options.sourceMaps ?? false,
+		filename,
+		jsescOption: { minimal: true }
+	}, code);
+	return {
+		code: result.code,
+		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];
+	return null;
+}
+function entryValue(entry) {
+	if (t.isObjectProperty(entry) && t.isObjectExpression(entry.value)) return entry.value;
+	return null;
+}
+/** A member of an entry object: `render`/`execute`/`type`, as property or method. */
+function findMember(object, name) {
+	return object.properties.find((p) => (t.isObjectProperty(p) || t.isObjectMethod(p)) && memberName(p.key, p.computed) === name);
+}
+function removeMember(object, name) {
+	object.properties = object.properties.filter((p) => !((t.isObjectProperty(p) || t.isObjectMethod(p)) && memberName(p.key, p.computed) === name));
+}
+/** The `BlockStatement` body of an `execute` member, if it has one. */
+function executeBody(member) {
+	if (t.isObjectMethod(member)) return member.body;
+	const value = member.value;
+	if ((t.isArrowFunctionExpression(value) || t.isFunctionExpression(value)) && t.isBlockStatement(value.body)) return value.body;
+}
+/** Whether an `execute` opts into the client via a leading `"use client"`. */
+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" });
+}
+/** Drops the `"use client"` directive from an `execute` body (kept frontend). */
+function stripUseClient(member) {
+	const body = executeBody(member);
+	if (body) body.directives = body.directives.filter((d) => d.value.value !== "use client");
+}
+/**
+* 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.
+*/
+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";
+	return executeIsClient(execute) ? "frontend" : "backend";
+}
+/** 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 memberName(key, computed) {
+	if (computed) return void 0;
+	if (t.isIdentifier(key)) return key.name;
+	if (t.isStringLiteral(key)) return key.value;
+}
+/**
+* Removes declarations and import specifiers left unreferenced after region
+* removal, to a fixpoint (a dropped helper frees what it used). Keeps exports,
+* side-effect imports, and possibly-side-effectful initializers.
+*/
+function pruneUnused(ast) {
+	const hadSpecifiers = /* @__PURE__ */ new WeakSet();
+	for (const stmt of ast.program.body) if (t.isImportDeclaration(stmt) && stmt.specifiers.length > 0) hadSpecifiers.add(stmt);
+	let removedSomething = true;
+	while (removedSomething) {
+		removedSomething = false;
+		traverse(ast, { Program(path) {
+			path.scope.crawl();
+			const isUnused = (name) => {
+				const binding = path.scope.getBinding(name);
+				return !!binding && !binding.referenced;
+			};
+			path.node.body = path.node.body.filter((stmt) => {
+				if ((t.isFunctionDeclaration(stmt) || t.isClassDeclaration(stmt)) && stmt.id && isUnused(stmt.id.name)) {
+					removedSomething = true;
+					return false;
+				}
+				if (t.isVariableDeclaration(stmt)) {
+					stmt.declarations = stmt.declarations.filter((decl) => {
+						const names = Object.keys(t.getBindingIdentifiers(decl.id));
+						if (names.length > 0 && isPlainPattern(decl.id) && isRemovableInit(decl.init) && names.every(isUnused)) {
+							removedSomething = true;
+							return false;
+						}
+						return true;
+					});
+					if (stmt.declarations.length === 0) return false;
+				}
+				return true;
+			});
+			path.stop();
+		} });
+	}
+	traverse(ast, { Program(path) {
+		path.scope.crawl();
+		for (const stmt of path.node.body) {
+			if (!t.isImportDeclaration(stmt)) continue;
+			stmt.specifiers = stmt.specifiers.filter((spec) => {
+				const binding = path.scope.getBinding(spec.local.name);
+				return binding ? binding.referenced : true;
+			});
+		}
+		path.node.body = path.node.body.filter((stmt) => !(t.isImportDeclaration(stmt) && stmt.specifiers.length === 0 && hadSpecifiers.has(stmt)));
+		path.stop();
+	} });
+}
+/**
+* Whether a binding pattern is side-effect-free to drop: a plain identifier, or
+* an object/array pattern of plain bindings — no default values
+* (`{ a = expr }`) or computed keys (`{ [expr]: a }`), which would evaluate (and
+* thus could have side effects) at destructuring time.
+*/
+function isPlainPattern(node) {
+	if (t.isIdentifier(node)) return true;
+	if (t.isObjectPattern(node)) return node.properties.every((p) => t.isRestElement(p) ? isPlainPattern(p.argument) : !p.computed && isPlainPattern(p.value));
+	if (t.isArrayPattern(node)) return node.elements.every((el) => el == null || isPlainPattern(el));
+	return false;
+}
+/** Whether a variable initializer is safe to drop (no observable side effects). */
+function isRemovableInit(node) {
+	if (node == null) return true;
+	if (t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node)) return isRemovableInit(node.expression);
+	if (t.isArrayExpression(node)) return node.elements.every((el) => el == null || t.isExpression(el) && isRemovableInit(el));
+	if (t.isObjectExpression(node)) return node.properties.every((p) => t.isObjectProperty(p) && !p.computed && t.isExpression(p.value) && isRemovableInit(p.value));
+	if (t.isTemplateLiteral(node)) return node.expressions.every((e) => t.isExpression(e) && isRemovableInit(e));
+	return t.isArrowFunctionExpression(node) || t.isFunctionExpression(node) || t.isClassExpression(node) || t.isIdentifier(node) || t.isMemberExpression(node) && !node.computed || t.isJSXElement(node) || t.isJSXFragment(node) || t.isLiteral(node);
+}
+//#endregion
+export { GenerativeCompileError, compileGenerative, isGenerativeModule };
+
+//# sourceMappingURL=compile.js.map

package/dist/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","names":[],"sources":["../src/compile.ts"],"sourcesContent":["import { parse } from \"@babel/parser\";\nimport _traverse, { type NodePath } from \"@babel/traverse\";\nimport _generate from \"@babel/generator\";\nimport * as t from \"@babel/types\";\nimport { DIRECTIVE, type Target } from \"./constants\";\n\n// @babel/traverse and @babel/generator are CJS; their default export is the\n// function itself under some interop and `{ default }` under others.\nconst traverse = (\n  typeof _traverse === \"function\" ? _traverse : (_traverse as any).default\n) as typeof _traverse;\nconst generate = (\n  typeof _generate === \"function\" ? _generate : (_generate as any).default\n) as typeof _generate;\n\nexport type ToolType = \"frontend\" | \"backend\" | \"human\";\n\nexport interface CompileOptions {\n  /** Which build target to emit. */\n  target: Target;\n  /** Source filename, used for error messages and source maps. */\n  filename?: string;\n  /** Emit a source map alongside the code. */\n  sourceMaps?: boolean;\n  /**\n   * Whether the `server` target prepends `import \"server-only\"` when it keeps a\n   * backend `execute`. Defaults to `true` (the Next.js/RSC convention, where the\n   * guard fires via the `react-server` condition). Set `false` for bundlers\n   * without a `react-server` layer (e.g. a Vite/TanStack Start `ssr` build),\n   * where the split is already structural and importing `server-only` would\n   * throw — see the Vite integration.\n   */\n  injectServerOnly?: boolean;\n}\n\nexport interface CompileResult {\n  code: string;\n  map?: object | null;\n}\n\n/** Thrown when a `\"use generative\"` file violates an authoring constraint. */\nexport class GenerativeCompileError extends Error {\n  constructor(message: string, filename?: string) {\n    super(`[assistant-ui/next]${filename ? ` ${filename}:` : \"\"} ${message}`);\n    this.name = \"GenerativeCompileError\";\n  }\n}\n\n/** Whether a source string opts into generative compilation via the directive. */\nexport function isGenerativeModule(code: string): boolean {\n  // The directive must be a leading statement, preceded only by an optional BOM,\n  // whitespace, and line/block comments. Scanned linearly — a regex over the\n  // comment prefix is prone to catastrophic backtracking on crafted input.\n  let i = code.charCodeAt(0) === 0xfeff ? 1 : 0;\n  for (;;) {\n    while (i < code.length && /\\s/.test(code[i]!)) i++;\n    if (code.startsWith(\"//\", i)) {\n      const nl = code.indexOf(\"\\n\", i);\n      if (nl === -1) return false;\n      i = nl + 1;\n    } else if (code.startsWith(\"/*\", i)) {\n      const end = code.indexOf(\"*/\", i + 2);\n      if (end === -1) return false;\n      i = end + 2;\n    } else {\n      break;\n    }\n  }\n  return (\n    code.startsWith(`\"${DIRECTIVE}\"`, i) || code.startsWith(`'${DIRECTIVE}'`, i)\n  );\n}\n\n/**\n * Rewrites a `\"use generative\"` module for a single build target, keeping only the\n * regions that target needs and pruning the imports the dropped regions used.\n */\nexport function compileGenerative(\n  code: string,\n  options: CompileOptions,\n): CompileResult {\n  const { target, filename } = options;\n\n  const ast = parse(code, {\n    sourceType: \"module\",\n    plugins: [\"typescript\", \"jsx\", \"explicitResourceManagement\"],\n  });\n\n  if (!ast.program.directives.some((d) => d.value.value === DIRECTIVE)) {\n    throw new GenerativeCompileError(\n      `missing \"${DIRECTIVE}\" directive`,\n      filename,\n    );\n  }\n\n  const object = findDefaultExportObject(ast, filename);\n\n  let keptRender = false;\n  let keptBackendExecute = false;\n\n  for (const entry of object.properties) {\n    const value = entryValue(entry);\n    if (!value) {\n      // A non-inline tool (spread, method, or a call like `makeTool()`) can't be\n      // analyzed, so its `execute` would pass through to the client unstripped.\n      throw new GenerativeCompileError(\n        \"each tool must be an inline object literal (`name: { ... }`) so its \" +\n          \"`execute` can be routed\",\n        filename,\n      );\n    }\n\n    // Nature is inferred from `execute` (see inferToolType), not an authored\n    // `type`. The resolved type is written back below so the runtime keeps it.\n    const type = inferToolType(value, filename);\n    const hasRender = !!findMember(value, \"render\");\n    const execute = findMember(value, \"execute\");\n\n    if ((type === \"frontend\" || type === \"human\") && !hasRender) {\n      throw new GenerativeCompileError(\n        `a ${type} tool must declare a \\`render\\` (it has no server execute to show otherwise)`,\n        filename,\n      );\n    }\n\n    if (target === \"client\") {\n      // A frontend execute stays (its `\"use client\"` marker is no longer needed\n      // once the module is client); a backend execute and a human `hitl()`\n      // sentinel are both dropped.\n      if (execute && type === \"frontend\") stripUseClient(execute);\n      else if (execute) removeMember(value, \"execute\");\n      if (hasRender) keptRender = true;\n    } else {\n      // server: render is never needed; only a backend execute survives.\n      if (hasRender) removeMember(value, \"render\");\n      if (execute && type !== \"backend\") removeMember(value, \"execute\");\n      if (execute && type === \"backend\") keptBackendExecute = true;\n    }\n\n    setToolType(value, type);\n  }\n\n  pruneUnused(ast);\n\n  // Replace the module directives with the target-appropriate one.\n  ast.program.directives = ast.program.directives.filter(\n    (d) => d.value.value !== DIRECTIVE && d.value.value !== \"use client\",\n  );\n  if (target === \"client\" && keptRender) {\n    ast.program.directives.unshift(\n      t.directive(t.directiveLiteral(\"use client\")),\n    );\n  }\n  if (\n    target === \"server\" &&\n    keptBackendExecute &&\n    (options.injectServerOnly ?? true)\n  ) {\n    ast.program.body.unshift(\n      t.importDeclaration([], t.stringLiteral(\"server-only\")),\n    );\n  }\n\n  const result = generate(\n    ast,\n    {\n      sourceMaps: options.sourceMaps ?? false,\n      filename,\n      jsescOption: { minimal: true },\n    },\n    code,\n  );\n\n  return { code: result.code, map: result.map };\n}\n\nfunction findDefaultExportObject(\n  ast: t.File,\n  filename: string | undefined,\n): t.ObjectExpression {\n  let object: t.ObjectExpression | null = null;\n  let sawDefault = false;\n\n  for (const stmt of ast.program.body) {\n    if (!t.isExportDefaultDeclaration(stmt)) continue;\n    sawDefault = true;\n    object = unwrapDefineToolkit(stmt.declaration);\n    // Emit the bare object literal, dropping the `defineToolkit(...)` wrapper\n    // (and the import it pulled).\n    if (object) stmt.declaration = object;\n  }\n\n  if (!sawDefault) {\n    throw new GenerativeCompileError(\"missing a default export\", filename);\n  }\n  if (!object) {\n    throw new GenerativeCompileError(\n      \"the default export must be `defineToolkit({ ... })` (imported from \" +\n        '\"@assistant-ui/react\"); wrapping is required so a backend `execute` ' +\n        \"can't be authored in a way that reaches the client\",\n      filename,\n    );\n  }\n  return object;\n}\n\n/**\n * Unwraps the required `defineToolkit({ ... })` wrapper (through `satisfies`/`as`\n * and parens) to the underlying object literal. Anything else — a bare object, a\n * `satisfies Toolkit` without the wrapper, some other call — yields `null` so the\n * caller errors.\n */\nfunction unwrapDefineToolkit(node: t.Node): t.ObjectExpression | null {\n  if (t.isTSSatisfiesExpression(node) || t.isTSAsExpression(node)) {\n    return unwrapDefineToolkit(node.expression);\n  }\n  if (t.isParenthesizedExpression(node)) {\n    return unwrapDefineToolkit(node.expression);\n  }\n  if (\n    t.isCallExpression(node) &&\n    t.isIdentifier(node.callee, { name: \"defineToolkit\" }) &&\n    t.isObjectExpression(node.arguments[0])\n  ) {\n    return node.arguments[0];\n  }\n  return null;\n}\n\ntype Entry = t.ObjectExpression[\"properties\"][number];\n\nfunction entryValue(entry: Entry): t.ObjectExpression | null {\n  if (t.isObjectProperty(entry) && t.isObjectExpression(entry.value)) {\n    return entry.value;\n  }\n  return null;\n}\n\n/** A member of an entry object: `render`/`execute`/`type`, as property or method. */\nfunction findMember(\n  object: t.ObjectExpression,\n  name: string,\n): t.ObjectProperty | t.ObjectMethod | undefined {\n  return object.properties.find(\n    (p): p is t.ObjectProperty | t.ObjectMethod =>\n      (t.isObjectProperty(p) || t.isObjectMethod(p)) &&\n      memberName(p.key, p.computed) === name,\n  );\n}\n\nfunction removeMember(object: t.ObjectExpression, name: string): void {\n  object.properties = object.properties.filter(\n    (p) =>\n      !(\n        (t.isObjectProperty(p) || t.isObjectMethod(p)) &&\n        memberName(p.key, p.computed) === name\n      ),\n  );\n}\n\n/** The `BlockStatement` body of an `execute` member, if it has one. */\nfunction executeBody(\n  member: t.ObjectProperty | t.ObjectMethod,\n): t.BlockStatement | undefined {\n  if (t.isObjectMethod(member)) return member.body;\n  const value = member.value;\n  if (\n    (t.isArrowFunctionExpression(value) || t.isFunctionExpression(value)) &&\n    t.isBlockStatement(value.body)\n  ) {\n    return value.body;\n  }\n  return undefined;\n}\n\n/** Whether an `execute` opts into the client via a leading `\"use client\"`. */\nfunction executeIsClient(member: t.ObjectProperty | t.ObjectMethod): boolean {\n  return !!executeBody(member)?.directives.some(\n    (d) => d.value.value === \"use client\",\n  );\n}\n\n/** Whether an `execute` is the `hitl()` human-in-the-loop sentinel. */\nfunction executeIsHitl(member: t.ObjectProperty | t.ObjectMethod): boolean {\n  return (\n    t.isObjectProperty(member) &&\n    t.isCallExpression(member.value) &&\n    t.isIdentifier(member.value.callee, { name: \"hitl\" })\n  );\n}\n\n/** Drops the `\"use client\"` directive from an `execute` body (kept frontend). */\nfunction stripUseClient(member: t.ObjectProperty | t.ObjectMethod): void {\n  const body = executeBody(member);\n  if (body) {\n    body.directives = body.directives.filter(\n      (d) => d.value.value !== \"use client\",\n    );\n  }\n}\n\n/**\n * The tool's nature, inferred from its (mandatory) `execute` rather than an\n * authored `type`: `hitl()` → `human`; `\"use client\"` → `frontend`; otherwise\n * `backend`. The loader writes the result back as a `type` field (see\n * {@link setToolType}) so the runtime keeps it.\n */\nfunction inferToolType(\n  object: t.ObjectExpression,\n  filename: string | undefined,\n): ToolType {\n  const execute = findMember(object, \"execute\");\n  if (!execute) {\n    throw new GenerativeCompileError(\n      \"every tool must declare an `execute`; use `hitl()` for a \" +\n        \"human-in-the-loop tool\",\n      filename,\n    );\n  }\n  if (executeIsHitl(execute)) return \"human\";\n  return executeIsClient(execute) ? \"frontend\" : \"backend\";\n}\n\n/** Writes the resolved `type` back onto the tool object (replacing any author's). */\nfunction setToolType(object: t.ObjectExpression, type: ToolType): void {\n  removeMember(object, \"type\");\n  // Append (not prepend) so the inferred type wins over any earlier spread.\n  object.properties.push(\n    t.objectProperty(t.identifier(\"type\"), t.stringLiteral(type)),\n  );\n}\n\nfunction memberName(\n  key: t.Node,\n  computed: boolean | undefined,\n): string | undefined {\n  if (computed) return undefined;\n  if (t.isIdentifier(key)) return key.name;\n  if (t.isStringLiteral(key)) return key.value;\n  return undefined;\n}\n\n/**\n * Removes declarations and import specifiers left unreferenced after region\n * removal, to a fixpoint (a dropped helper frees what it used). Keeps exports,\n * side-effect imports, and possibly-side-effectful initializers.\n */\nfunction pruneUnused(ast: t.File): void {\n  const hadSpecifiers = new WeakSet<t.ImportDeclaration>();\n  for (const stmt of ast.program.body) {\n    if (t.isImportDeclaration(stmt) && stmt.specifiers.length > 0) {\n      hadSpecifiers.add(stmt);\n    }\n  }\n\n  let removedSomething = true;\n  while (removedSomething) {\n    removedSomething = false;\n    traverse(ast, {\n      Program(path: NodePath<t.Program>) {\n        path.scope.crawl();\n        const isUnused = (name: string): boolean => {\n          const binding = path.scope.getBinding(name);\n          return !!binding && !binding.referenced;\n        };\n\n        path.node.body = path.node.body.filter((stmt) => {\n          if (\n            (t.isFunctionDeclaration(stmt) || t.isClassDeclaration(stmt)) &&\n            stmt.id &&\n            isUnused(stmt.id.name)\n          ) {\n            removedSomething = true;\n            return false;\n          }\n          if (t.isVariableDeclaration(stmt)) {\n            stmt.declarations = stmt.declarations.filter((decl) => {\n              // Handles destructuring too: drop the declarator only when *every*\n              // bound name is unused (else a `const { a } = server` survives and\n              // keeps a server import in the client graph). Restricted to plain\n              // patterns so a default/computed-key side effect isn't dropped.\n              const names = Object.keys(t.getBindingIdentifiers(decl.id));\n              if (\n                names.length > 0 &&\n                isPlainPattern(decl.id) &&\n                isRemovableInit(decl.init) &&\n                names.every(isUnused)\n              ) {\n                removedSomething = true;\n                return false;\n              }\n              return true;\n            });\n            if (stmt.declarations.length === 0) return false;\n          }\n          return true;\n        });\n        path.stop();\n      },\n    });\n  }\n\n  traverse(ast, {\n    Program(path: NodePath<t.Program>) {\n      path.scope.crawl();\n      for (const stmt of path.node.body) {\n        if (!t.isImportDeclaration(stmt)) continue;\n        stmt.specifiers = stmt.specifiers.filter((spec) => {\n          const binding = path.scope.getBinding(spec.local.name);\n          return binding ? binding.referenced : true;\n        });\n      }\n      path.node.body = path.node.body.filter(\n        (stmt) =>\n          !(\n            t.isImportDeclaration(stmt) &&\n            stmt.specifiers.length === 0 &&\n            hadSpecifiers.has(stmt)\n          ),\n      );\n      path.stop();\n    },\n  });\n}\n\n/**\n * Whether a binding pattern is side-effect-free to drop: a plain identifier, or\n * an object/array pattern of plain bindings — no default values\n * (`{ a = expr }`) or computed keys (`{ [expr]: a }`), which would evaluate (and\n * thus could have side effects) at destructuring time.\n */\nfunction isPlainPattern(node: t.Node): boolean {\n  if (t.isIdentifier(node)) return true;\n  if (t.isObjectPattern(node)) {\n    return node.properties.every((p) =>\n      t.isRestElement(p)\n        ? isPlainPattern(p.argument)\n        : !p.computed && isPlainPattern(p.value),\n    );\n  }\n  if (t.isArrayPattern(node)) {\n    return node.elements.every((el) => el == null || isPlainPattern(el));\n  }\n  return false; // AssignmentPattern (default), member expr, etc.\n}\n\n/** Whether a variable initializer is safe to drop (no observable side effects). */\nfunction isRemovableInit(node: t.Expression | null | undefined): boolean {\n  if (node == null) return true;\n  if (t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node)) {\n    return isRemovableInit(node.expression);\n  }\n  // Containers are removable only if every element is — a nested call (e.g.\n  // `[track()]`) has an observable side effect that dropping would lose.\n  if (t.isArrayExpression(node)) {\n    return node.elements.every(\n      (el) => el == null || (t.isExpression(el) && isRemovableInit(el)),\n    );\n  }\n  if (t.isObjectExpression(node)) {\n    return node.properties.every(\n      (p) =>\n        t.isObjectProperty(p) &&\n        !p.computed &&\n        t.isExpression(p.value) &&\n        isRemovableInit(p.value),\n    );\n  }\n  if (t.isTemplateLiteral(node)) {\n    return node.expressions.every(\n      (e) => t.isExpression(e) && isRemovableInit(e),\n    );\n  }\n  return (\n    t.isArrowFunctionExpression(node) ||\n    t.isFunctionExpression(node) ||\n    t.isClassExpression(node) ||\n    t.isIdentifier(node) ||\n    // non-computed only — `obj[fn()]` could hide a side-effectful key\n    (t.isMemberExpression(node) && !node.computed) ||\n    t.isJSXElement(node) ||\n    t.isJSXFragment(node) ||\n    t.isLiteral(node)\n  );\n}\n"],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+//#region src/constants.d.ts
+/** The directive a module uses to opt into generative compilation. */
+declare const DIRECTIVE = "use generative";
+/** Build target a generative module is compiled for. */
+type Target = "client" | "server";
+//#endregion
+export { DIRECTIVE, Target };
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","names":[],"sources":["../src/constants.ts"],"mappings":";;cACa,SAAA;;KAGD,MAAA"}

package/dist/constants.js

@@ -0,0 +1,7 @@
+//#region src/constants.ts
+/** The directive a module uses to opt into generative compilation. */
+const DIRECTIVE = "use generative";
+//#endregion
+export { DIRECTIVE };
+
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/** The directive a module uses to opt into generative compilation. */\nexport const DIRECTIVE = \"use generative\";\n\n/** Build target a generative module is compiled for. */\nexport type Target = \"client\" | \"server\";\n"],"mappings":";;AACA,MAAa,YAAY"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { DIRECTIVE, Target } from "./constants.js";
+import { CompileOptions, CompileResult, GenerativeCompileError, ToolType, compileGenerative, isGenerativeModule } from "./compile.js";
+export { type CompileOptions, type CompileResult, DIRECTIVE, GenerativeCompileError, type Target, type ToolType, compileGenerative, isGenerativeModule };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { DIRECTIVE } from "./constants.js";
+import { GenerativeCompileError, compileGenerative, isGenerativeModule } from "./compile.js";
+export { DIRECTIVE, GenerativeCompileError, compileGenerative, isGenerativeModule };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@assistant-ui/x-generative-compiler",
+  "private": false,
+  "version": "0.0.1",
+  "description": "Internal: the framework-agnostic \"use generative\" compiler that splits a colocated tool (schema + server-only execute + client-only render) into per-target builds. Shared by @assistant-ui/next and @assistant-ui/vite.",
+  "keywords": [
+    "assistant-ui",
+    "generative",
+    "compiler",
+    "use generative",
+    "rsc",
+    "internal"
+  ],
+  "author": "AgentbaseAI Inc.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "aui-build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.28.3",
+    "@babel/parser": "^7.28.4",
+    "@babel/traverse": "^7.28.4",
+    "@babel/types": "^7.28.4"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@types/babel__generator": "^7.27.0",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^25.9.1",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://www.assistant-ui.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assistant-ui/assistant-ui.git",
+    "directory": "packages/x-generative-compiler"
+  },
+  "bugs": {
+    "url": "https://github.com/assistant-ui/assistant-ui/issues"
+  }
+}

package/src/compile.test.ts

@@ -0,0 +1,267 @@
+import { describe, it, expect } from "vitest";
+import {
+  compileGenerative,
+  isGenerativeModule,
+  GenerativeCompileError,
+} from "./compile";
+
+const source = `"use generative";
+import { z } from "zod";
+import { db } from "@/db";
+import { track } from "@/analytics";
+import { Chart } from "@/ui/chart";
+import { defineToolkit } from "@assistant-ui/react";
+
+export default defineToolkit({
+  weather: {
+    description: "Show the weather.",
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => db.weather.get(city),
+    render: (props) => <Chart data={props} />,
+  },
+  toast: {
+    description: "Show a toast.",
+    parameters: z.object({ msg: z.string() }),
+    execute: async ({ msg }) => {
+      "use client";
+      return track(msg);
+    },
+    render: (props) => <div>{props.msg}</div>,
+  },
+});
+`;
+
+const server = () => compileGenerative(source, { target: "server" }).code;
+const client = () => compileGenerative(source, { target: "client" }).code;
+
+describe("compileGenerative — server target", () => {
+  const code = server();
+
+  it("keeps the schema", () => {
+    expect(code).toContain('import { z } from "zod"');
+    expect(code).toContain("z.object");
+    expect(code).toContain('description: "Show the weather."');
+  });
+
+  it("keeps a backend execute and guards it with server-only", () => {
+    expect(code).toContain('import "server-only"');
+    expect(code).toContain("db.weather.get");
+    expect(code).toContain('import { db } from "@/db"');
+  });
+
+  it("writes the inferred type back onto each tool", () => {
+    expect(code).toContain('type: "backend"'); // weather: execute, no "use client"
+    expect(code).toContain('type: "frontend"'); // toast: execute + "use client"
+  });
+
+  it("drops all render and its client imports", () => {
+    expect(code).not.toContain("Chart");
+    expect(code).not.toContain("<div");
+    expect(code).not.toMatch(/render\s*:/);
+  });
+
+  it("drops a frontend execute and its client imports", () => {
+    expect(code).not.toContain("track");
+    expect(code).not.toContain("@/analytics");
+  });
+
+  it("strips the use generative directive and adds no use client", () => {
+    expect(code).not.toContain("use generative");
+    expect(code).not.toContain("use client");
+  });
+});
+
+describe("compileGenerative — client target", () => {
+  const code = client();
+
+  it("marks the module use client and keeps render", () => {
+    expect(code.trimStart().startsWith('"use client"')).toBe(true);
+    expect(code).toContain("<Chart");
+    expect(code).toContain("<div");
+    expect(code).toContain('import { Chart } from "@/ui/chart"');
+  });
+
+  it("keeps the schema for parsing", () => {
+    expect(code).toContain('import { z } from "zod"');
+    expect(code).toContain("z.object");
+  });
+
+  it("keeps a frontend execute (and drops its `use client` marker)", () => {
+    expect(code).toContain("track(msg)");
+    expect(code).toContain("@/analytics");
+    // exactly one "use client" — the module directive, not the execute body's
+    expect(code.match(/use client/g)?.length).toBe(1);
+  });
+
+  it("writes the inferred type back onto each tool", () => {
+    expect(code).toContain('type: "backend"'); // weather (schema-only on client)
+    expect(code).toContain('type: "frontend"'); // toast
+  });
+
+  it("drops a backend execute and its server-only imports", () => {
+    expect(code).not.toContain("db.weather.get");
+    expect(code).not.toContain("@/db");
+    expect(code).not.toContain("server-only");
+  });
+});
+
+describe("compileGenerative — local dead-code elimination", () => {
+  const withHelpers = `"use generative";
+import { z } from "zod";
+import { cn } from "@/lib/utils";
+import { db } from "@/db";
+
+const Badge = ({ label }) => <span className={cn("badge")}>{label}</span>;
+import { defineToolkit } from "@assistant-ui/react";
+
+export default defineToolkit({
+  weather: {
+    description: "weather",
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => db.weather.get(city),
+    render: (props) => <Badge label={props.city} />,
+  },
+});
+`;
+
+  it("strips a local helper component (and its imports) from the server", () => {
+    const code = compileGenerative(withHelpers, { target: "server" }).code;
+    expect(code).not.toContain("Badge");
+    expect(code).not.toContain("@/lib/utils");
+    expect(code).not.toContain("className");
+    expect(code).toContain("db.weather.get");
+    expect(code).toContain('import "server-only"');
+  });
+
+  it("keeps the local helper on the client", () => {
+    const code = compileGenerative(withHelpers, { target: "client" }).code;
+    expect(code).toContain("Badge");
+    expect(code).toContain("@/lib/utils");
+    expect(code).not.toContain("@/db");
+  });
+
+  it("prunes an unused destructured server binding from the client", () => {
+    const src = `"use generative";
+import { defineToolkit } from "@assistant-ui/react";
+import { db } from "@/db";
+const { getWeather } = db;
+export default defineToolkit({
+  weather: {
+    execute: async ({ city }) => getWeather(city),
+    render: () => null,
+  },
+});`;
+    const client = compileGenerative(src, { target: "client" }).code;
+    expect(client).not.toContain("getWeather");
+    expect(client).not.toContain("@/db");
+    expect(compileGenerative(src, { target: "server" }).code).toContain(
+      "getWeather",
+    );
+  });
+});
+
+describe("compileGenerative — diagnostics", () => {
+  it("rejects a module without the directive", () => {
+    expect(() =>
+      compileGenerative(`export default {} satisfies Toolkit;`, {
+        target: "server",
+      }),
+    ).toThrow(GenerativeCompileError);
+  });
+
+  it("strips a define-style wrapper and prunes its import", () => {
+    const wrapped = `"use generative";
+import { z } from "zod";
+import { db } from "@/db";
+import { defineToolkit } from "@assistant-ui/react";
+export default defineToolkit({
+  weather: {
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => db.get(city),
+    render: (props) => <span>{props.city}</span>,
+  },
+});`;
+    const serverCode = compileGenerative(wrapped, { target: "server" }).code;
+    // wrapper + its import gone; bare object with execute remains.
+    expect(serverCode).not.toContain("defineToolkit");
+    expect(serverCode).not.toContain("@assistant-ui/react");
+    expect(serverCode).toContain("db.get");
+    expect(serverCode).not.toContain("<span");
+
+    const clientCode = compileGenerative(wrapped, { target: "client" }).code;
+    expect(clientCode).not.toContain("defineToolkit");
+    expect(clientCode).not.toContain("@assistant-ui/react");
+    expect(clientCode).toContain("<span");
+    expect(clientCode).not.toContain("@/db");
+  });
+
+  it("requires the defineToolkit() wrapper", () => {
+    expect(() =>
+      compileGenerative(
+        `"use generative";\nexport default { a: { execute: async () => 1 } };`,
+        { target: "server" },
+      ),
+    ).toThrow(/defineToolkit/);
+    expect(() =>
+      compileGenerative(`"use generative";\nexport default makeToolkit();`, {
+        target: "server",
+      }),
+    ).toThrow(/defineToolkit/);
+  });
+
+  it("rejects a tool that isn't an inline object literal", () => {
+    expect(() =>
+      compileGenerative(
+        `"use generative";\nimport { defineToolkit } from "@assistant-ui/react";\nexport default defineToolkit({ weather: makeTool() });`,
+        { target: "server" },
+      ),
+    ).toThrow(/inline object literal/);
+  });
+
+  it("requires a render for human/frontend tools", () => {
+    expect(() =>
+      compileGenerative(
+        `"use generative";\nimport { defineToolkit, hitl } from "@assistant-ui/react";\nexport default defineToolkit({ ask: { execute: hitl() } });`,
+        { target: "client" },
+      ),
+    ).toThrow(/must declare a `render`/);
+  });
+
+  it("requires every tool to declare an execute", () => {
+    expect(() =>
+      compileGenerative(
+        `"use generative";\nimport { defineToolkit } from "@assistant-ui/react";\nexport default defineToolkit({ ask: { render: () => null } });`,
+        { target: "client" },
+      ),
+    ).toThrow(/must declare an `execute`/);
+  });
+
+  it("infers `human` from execute: hitl() and drops it on both builds", () => {
+    const src = `"use generative";\nimport { defineToolkit, hitl } from "@assistant-ui/react";\nexport default defineToolkit({ ask: { execute: hitl(), render: () => null } });`;
+    const server = compileGenerative(src, { target: "server" }).code;
+    expect(server).toContain('type: "human"');
+    expect(server).not.toContain("hitl"); // sentinel + its import pruned
+    const client = compileGenerative(src, { target: "client" }).code;
+    expect(client).toContain('type: "human"');
+    expect(client).not.toContain("hitl");
+    expect(client).toContain("render");
+  });
+
+  it("infers `frontend` from a `use client` execute and keeps it client-side", () => {
+    const src = `"use generative";\nimport { defineToolkit } from "@assistant-ui/react";\nimport { track } from "@/a";\nexport default defineToolkit({ t: { execute: async () => { "use client"; return track(); }, render: () => null } });`;
+    const server = compileGenerative(src, { target: "server" }).code;
+    expect(server).toContain('type: "frontend"');
+    expect(server).not.toContain("track"); // frontend execute dropped on server
+    const client = compileGenerative(src, { target: "client" }).code;
+    expect(client).toContain('type: "frontend"');
+    expect(client).toContain("track()");
+  });
+
+  it("detects generative modules by directive", () => {
+    expect(isGenerativeModule(`"use generative";\nexport default {};`)).toBe(
+      true,
+    );
+    expect(isGenerativeModule(`// a comment\n"use generative";\n`)).toBe(true);
+    expect(isGenerativeModule(`export default {};`)).toBe(false);
+  });
+});

package/src/compile.ts

@@ -0,0 +1,485 @@
+import { parse } from "@babel/parser";
+import _traverse, { type NodePath } from "@babel/traverse";
+import _generate from "@babel/generator";
+import * as t from "@babel/types";
+import { DIRECTIVE, type Target } from "./constants";
+
+// @babel/traverse and @babel/generator are CJS; their default export is the
+// function itself under some interop and `{ default }` under others.
+const traverse = (
+  typeof _traverse === "function" ? _traverse : (_traverse as any).default
+) as typeof _traverse;
+const generate = (
+  typeof _generate === "function" ? _generate : (_generate as any).default
+) as typeof _generate;
+
+export type ToolType = "frontend" | "backend" | "human";
+
+export interface CompileOptions {
+  /** Which build target to emit. */
+  target: Target;
+  /** Source filename, used for error messages and source maps. */
+  filename?: string;
+  /** Emit a source map alongside the code. */
+  sourceMaps?: boolean;
+  /**
+   * Whether the `server` target prepends `import "server-only"` when it keeps a
+   * backend `execute`. Defaults to `true` (the Next.js/RSC convention, where the
+   * guard fires via the `react-server` condition). Set `false` for bundlers
+   * without a `react-server` layer (e.g. a Vite/TanStack Start `ssr` build),
+   * where the split is already structural and importing `server-only` would
+   * throw — see the Vite integration.
+   */
+  injectServerOnly?: boolean;
+}
+
+export interface CompileResult {
+  code: string;
+  map?: object | null;
+}
+
+/** Thrown when a `"use generative"` file violates an authoring constraint. */
+export class GenerativeCompileError extends Error {
+  constructor(message: string, filename?: string) {
+    super(`[assistant-ui/next]${filename ? ` ${filename}:` : ""} ${message}`);
+    this.name = "GenerativeCompileError";
+  }
+}
+
+/** Whether a source string opts into generative compilation via the directive. */
+export function isGenerativeModule(code: string): boolean {
+  // The directive must be a leading statement, preceded only by an optional BOM,
+  // whitespace, and line/block comments. Scanned linearly — a regex over the
+  // comment prefix is prone to catastrophic backtracking on crafted input.
+  let i = code.charCodeAt(0) === 0xfeff ? 1 : 0;
+  for (;;) {
+    while (i < code.length && /\s/.test(code[i]!)) i++;
+    if (code.startsWith("//", i)) {
+      const nl = code.indexOf("\n", i);
+      if (nl === -1) return false;
+      i = nl + 1;
+    } else if (code.startsWith("/*", i)) {
+      const end = code.indexOf("*/", i + 2);
+      if (end === -1) return false;
+      i = end + 2;
+    } else {
+      break;
+    }
+  }
+  return (
+    code.startsWith(`"${DIRECTIVE}"`, i) || code.startsWith(`'${DIRECTIVE}'`, i)
+  );
+}
+
+/**
+ * Rewrites a `"use generative"` module for a single build target, keeping only the
+ * regions that target needs and pruning the imports the dropped regions used.
+ */
+export function compileGenerative(
+  code: string,
+  options: CompileOptions,
+): CompileResult {
+  const { target, filename } = options;
+
+  const ast = parse(code, {
+    sourceType: "module",
+    plugins: ["typescript", "jsx", "explicitResourceManagement"],
+  });
+
+  if (!ast.program.directives.some((d) => d.value.value === DIRECTIVE)) {
+    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) {
+      // 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,
+      );
+    }
+
+    // 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");
+
+    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") {
+      // 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;
+    }
+
+    setToolType(value, type);
+  }
+
+  pruneUnused(ast);
+
+  // Replace the module directives with the target-appropriate one.
+  ast.program.directives = ast.program.directives.filter(
+    (d) => d.value.value !== DIRECTIVE && d.value.value !== "use client",
+  );
+  if (target === "client" && keptRender) {
+    ast.program.directives.unshift(
+      t.directive(t.directiveLiteral("use client")),
+    );
+  }
+  if (
+    target === "server" &&
+    keptBackendExecute &&
+    (options.injectServerOnly ?? true)
+  ) {
+    ast.program.body.unshift(
+      t.importDeclaration([], t.stringLiteral("server-only")),
+    );
+  }
+
+  const result = generate(
+    ast,
+    {
+      sourceMaps: options.sourceMaps ?? false,
+      filename,
+      jsescOption: { minimal: true },
+    },
+    code,
+  );
+
+  return { code: result.code, map: result.map };
+}
+
+function findDefaultExportObject(
+  ast: t.File,
+  filename: string | undefined,
+): t.ObjectExpression {
+  let object: t.ObjectExpression | null = null;
+  let sawDefault = false;
+
+  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;
+  }
+
+  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: t.Node): t.ObjectExpression | null {
+  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];
+  }
+  return null;
+}
+
+type Entry = t.ObjectExpression["properties"][number];
+
+function entryValue(entry: Entry): t.ObjectExpression | null {
+  if (t.isObjectProperty(entry) && t.isObjectExpression(entry.value)) {
+    return entry.value;
+  }
+  return null;
+}
+
+/** A member of an entry object: `render`/`execute`/`type`, as property or method. */
+function findMember(
+  object: t.ObjectExpression,
+  name: string,
+): t.ObjectProperty | t.ObjectMethod | undefined {
+  return object.properties.find(
+    (p): p is t.ObjectProperty | t.ObjectMethod =>
+      (t.isObjectProperty(p) || t.isObjectMethod(p)) &&
+      memberName(p.key, p.computed) === name,
+  );
+}
+
+function removeMember(object: t.ObjectExpression, name: string): void {
+  object.properties = object.properties.filter(
+    (p) =>
+      !(
+        (t.isObjectProperty(p) || t.isObjectMethod(p)) &&
+        memberName(p.key, p.computed) === name
+      ),
+  );
+}
+
+/** The `BlockStatement` body of an `execute` member, if it has one. */
+function executeBody(
+  member: t.ObjectProperty | t.ObjectMethod,
+): t.BlockStatement | undefined {
+  if (t.isObjectMethod(member)) return member.body;
+  const value = member.value;
+  if (
+    (t.isArrowFunctionExpression(value) || t.isFunctionExpression(value)) &&
+    t.isBlockStatement(value.body)
+  ) {
+    return value.body;
+  }
+  return undefined;
+}
+
+/** Whether an `execute` opts into the client via a leading `"use client"`. */
+function executeIsClient(member: t.ObjectProperty | t.ObjectMethod): boolean {
+  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: t.ObjectProperty | t.ObjectMethod): boolean {
+  return (
+    t.isObjectProperty(member) &&
+    t.isCallExpression(member.value) &&
+    t.isIdentifier(member.value.callee, { name: "hitl" })
+  );
+}
+
+/** Drops the `"use client"` directive from an `execute` body (kept frontend). */
+function stripUseClient(member: t.ObjectProperty | t.ObjectMethod): void {
+  const body = executeBody(member);
+  if (body) {
+    body.directives = body.directives.filter(
+      (d) => d.value.value !== "use client",
+    );
+  }
+}
+
+/**
+ * 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.
+ */
+function inferToolType(
+  object: t.ObjectExpression,
+  filename: string | undefined,
+): ToolType {
+  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";
+  return executeIsClient(execute) ? "frontend" : "backend";
+}
+
+/** Writes the resolved `type` back onto the tool object (replacing any author's). */
+function setToolType(object: t.ObjectExpression, type: ToolType): void {
+  removeMember(object, "type");
+  // Append (not prepend) so the inferred type wins over any earlier spread.
+  object.properties.push(
+    t.objectProperty(t.identifier("type"), t.stringLiteral(type)),
+  );
+}
+
+function memberName(
+  key: t.Node,
+  computed: boolean | undefined,
+): string | undefined {
+  if (computed) return undefined;
+  if (t.isIdentifier(key)) return key.name;
+  if (t.isStringLiteral(key)) return key.value;
+  return undefined;
+}
+
+/**
+ * Removes declarations and import specifiers left unreferenced after region
+ * removal, to a fixpoint (a dropped helper frees what it used). Keeps exports,
+ * side-effect imports, and possibly-side-effectful initializers.
+ */
+function pruneUnused(ast: t.File): void {
+  const hadSpecifiers = new WeakSet<t.ImportDeclaration>();
+  for (const stmt of ast.program.body) {
+    if (t.isImportDeclaration(stmt) && stmt.specifiers.length > 0) {
+      hadSpecifiers.add(stmt);
+    }
+  }
+
+  let removedSomething = true;
+  while (removedSomething) {
+    removedSomething = false;
+    traverse(ast, {
+      Program(path: NodePath<t.Program>) {
+        path.scope.crawl();
+        const isUnused = (name: string): boolean => {
+          const binding = path.scope.getBinding(name);
+          return !!binding && !binding.referenced;
+        };
+
+        path.node.body = path.node.body.filter((stmt) => {
+          if (
+            (t.isFunctionDeclaration(stmt) || t.isClassDeclaration(stmt)) &&
+            stmt.id &&
+            isUnused(stmt.id.name)
+          ) {
+            removedSomething = true;
+            return false;
+          }
+          if (t.isVariableDeclaration(stmt)) {
+            stmt.declarations = stmt.declarations.filter((decl) => {
+              // Handles destructuring too: drop the declarator only when *every*
+              // bound name is unused (else a `const { a } = server` survives and
+              // keeps a server import in the client graph). Restricted to plain
+              // patterns so a default/computed-key side effect isn't dropped.
+              const names = Object.keys(t.getBindingIdentifiers(decl.id));
+              if (
+                names.length > 0 &&
+                isPlainPattern(decl.id) &&
+                isRemovableInit(decl.init) &&
+                names.every(isUnused)
+              ) {
+                removedSomething = true;
+                return false;
+              }
+              return true;
+            });
+            if (stmt.declarations.length === 0) return false;
+          }
+          return true;
+        });
+        path.stop();
+      },
+    });
+  }
+
+  traverse(ast, {
+    Program(path: NodePath<t.Program>) {
+      path.scope.crawl();
+      for (const stmt of path.node.body) {
+        if (!t.isImportDeclaration(stmt)) continue;
+        stmt.specifiers = stmt.specifiers.filter((spec) => {
+          const binding = path.scope.getBinding(spec.local.name);
+          return binding ? binding.referenced : true;
+        });
+      }
+      path.node.body = path.node.body.filter(
+        (stmt) =>
+          !(
+            t.isImportDeclaration(stmt) &&
+            stmt.specifiers.length === 0 &&
+            hadSpecifiers.has(stmt)
+          ),
+      );
+      path.stop();
+    },
+  });
+}
+
+/**
+ * Whether a binding pattern is side-effect-free to drop: a plain identifier, or
+ * an object/array pattern of plain bindings — no default values
+ * (`{ a = expr }`) or computed keys (`{ [expr]: a }`), which would evaluate (and
+ * thus could have side effects) at destructuring time.
+ */
+function isPlainPattern(node: t.Node): boolean {
+  if (t.isIdentifier(node)) return true;
+  if (t.isObjectPattern(node)) {
+    return node.properties.every((p) =>
+      t.isRestElement(p)
+        ? isPlainPattern(p.argument)
+        : !p.computed && isPlainPattern(p.value),
+    );
+  }
+  if (t.isArrayPattern(node)) {
+    return node.elements.every((el) => el == null || isPlainPattern(el));
+  }
+  return false; // AssignmentPattern (default), member expr, etc.
+}
+
+/** Whether a variable initializer is safe to drop (no observable side effects). */
+function isRemovableInit(node: t.Expression | null | undefined): boolean {
+  if (node == null) return true;
+  if (t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node)) {
+    return isRemovableInit(node.expression);
+  }
+  // Containers are removable only if every element is — a nested call (e.g.
+  // `[track()]`) has an observable side effect that dropping would lose.
+  if (t.isArrayExpression(node)) {
+    return node.elements.every(
+      (el) => el == null || (t.isExpression(el) && isRemovableInit(el)),
+    );
+  }
+  if (t.isObjectExpression(node)) {
+    return node.properties.every(
+      (p) =>
+        t.isObjectProperty(p) &&
+        !p.computed &&
+        t.isExpression(p.value) &&
+        isRemovableInit(p.value),
+    );
+  }
+  if (t.isTemplateLiteral(node)) {
+    return node.expressions.every(
+      (e) => t.isExpression(e) && isRemovableInit(e),
+    );
+  }
+  return (
+    t.isArrowFunctionExpression(node) ||
+    t.isFunctionExpression(node) ||
+    t.isClassExpression(node) ||
+    t.isIdentifier(node) ||
+    // non-computed only — `obj[fn()]` could hide a side-effectful key
+    (t.isMemberExpression(node) && !node.computed) ||
+    t.isJSXElement(node) ||
+    t.isJSXFragment(node) ||
+    t.isLiteral(node)
+  );
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+/** The directive a module uses to opt into generative compilation. */
+export const DIRECTIVE = "use generative";
+
+/** Build target a generative module is compiled for. */
+export type Target = "client" | "server";

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  compileGenerative,
+  isGenerativeModule,
+  GenerativeCompileError,
+  type ToolType,
+  type CompileOptions,
+  type CompileResult,
+} from "./compile";
+export { DIRECTIVE, type Target } from "./constants";