fix(skills): serve agent-bundle/meta to rendered skills and compile their JSX without the consumer react runtime (#527)

* fix(skills): serve agent-bundle/meta to rendered skills and compile their JSX against the loader's element factory

Rendered SKILL.tsx modules evaluate through jiti during discovery, outside the
compiler's specifier replacement, so 'agent-bundle/meta' fell through to the
published module and threw AB4760 inside AB3003 (#440). The loader now aliases
the specifier to the same generated identity module the build stamps, fed from
one pluginIdentity() derivation normalization also uses for model.metadata.

The skill's JSX compiled against the consumer's react/jsx-runtime, which jiti
resolves without the process's --conditions while React's own inner
require('react') honours them; under the route-unit pool's react-server
condition the client jsx runtime met the server React and threw
(recentlyCreatedOwnerStacks) so inspectWorkbenchSurface failed with AB3005
(#441). The loader now aliases react/jsx-runtime and react/jsx-dev-runtime to
its own plain element factory: the Markdown renderer never needed React.

Fixes #440
Fixes #441

* chore: reference PR number in changeset

* fix(config): keep a malformed plugin block the validator's AB4000 when discovery derives the skill identity

Review: discovery dereferenced config.plugin.name before validateSource ran,
turning {} or plugin: null into a generic AB7000. declaredPluginIdentity()
returns undefined for an unusable plugin.name; the rendered skill then gets
no identity (AB3003) and validation reports AB4000 as before.

Author: ScriptedAlchemy

.changeset/440-441-rendered-skill-loader.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Let a rendered Skill (`src/skills/<name>/SKILL.tsx`) import `agent-bundle/meta` and evaluate independently of the process's `react` resolution. The skill loader now aliases `agent-bundle/meta` to the same generated identity module the compiler stamps into every built surface — `{ name, packageName, packageVersion, version }` derived from `plugin.name`, `package.json`, and the resolved plugin version — under `validate`, `build`, `inspect`, dev, the Workbench's source Skill documents, and `inspectWorkbenchSurface`, instead of failing with `AB3003` wrapping `AB4760`. The skill's JSX compiles against the loader's own element factory rather than the project's `react/jsx-runtime`, so `inspectWorkbenchSurface` no longer fails with `AB3005` (`recentlyCreatedOwnerStacks`) on a project with a rendered skill when the test runs under the `react-server` condition the `agentBundleRstest()` route-unit pool sets. Fixes #440 and #441 (#527)

docs/diagnostics.md

@@ -439,6 +439,15 @@ aliased module throws the same `AB4760` naming the compiler diagnostics and
 the recovery "fix them, then rerun Rstest" — the manifest's placeholder
 identity is never served as a real one.
 
+Rendered skills (`src/skills/<name>/SKILL.tsx`) evaluate during discovery,
+and the skill loader aliases the specifier to the same generated module fed
+from the identity normalization stamps into the model, so a skill importing
+`agent-bundle/meta` compiles under `validate`, `build`, `inspect`, dev, and
+`inspectWorkbenchSurface` (#440). Only a direct `parseSkill` call without a
+project identity leaves the specifier to resolve as the project resolves
+`agent-bundle`; the published module then raises this diagnostic inside the
+skill's `AB3003`.
+
 | Code | Severity | Trigger | Recovery |
 | --- | --- | --- | --- |
 | `AB4760` | error | A module evaluated the published `agent-bundle/meta` outside a surface Agent Bundle compiles — typically a unit test pool not built from the Rstest preset, or a hand-run script importing plugin source. | Run the test under `agentBundleRstest()` or `agentBundleBrowserRstest()` from `agent-bundle/rstest` (pass `include` to cover a plain unit pool), or compile the surface with `agent-bundle build`. In a custom test runner, alias `agent-bundle/meta` (`resolve.alias`, exact match) to a module with the named exports `{ name, packageName, packageVersion, version, meta }` — `meta` the frozen object of the other four, exported as both the named binding and the default export — computed from the project's `agent-bundle.config.ts` plugin name and `package.json` version; the `.agent-bundle/test/meta.mjs` module `agentBundleRstest()` writes is that module. |

docs/entry-conventions.md

@@ -914,6 +914,14 @@ route-unit level, `renderRoute`, and `invokeCli` alike — with the identity
 does not use the preset must add the same alias; the `AB4760` recovery text
 spells it out (see [Diagnostics](diagnostics.md#build-time-identity-outside-the-compiler-ab4760)).
 
+Rendered skills are not outside it either (#440): `src/skills/<name>/SKILL.tsx`
+evaluates during discovery, before any bundle exists, and the skill loader
+aliases the specifier to the same generated module fed from the identity
+normalization is about to stamp into the model (`plugin.name`, the
+`package.json` axes, the resolved version). A skill that prints `version`
+prints the one its artifact manifest reports, under `validate`, `build`,
+`inspect`, dev, the Workbench's source documents, and `inspectWorkbenchSurface`.
+
 ## Prebuilt payloads — package what you compiled yourself
 
 Some projects legitimately own their compilation — a coordinated

packages/agent-bundle/src/config/discover.ts

@@ -3,6 +3,7 @@ import { basename, dirname, relative, resolve } from 'node:path';
 
 import fastGlob from 'fast-glob';
 
+import { projectMeta } from '../build/meta.ts';
 import { isErrno } from '../core/errors.ts';
 import { isInside } from '../core/paths.ts';
 import { isRecord } from '../core/strict-json.ts';
@@ -11,6 +12,7 @@ import { compileRouteGraph, isEmptyRouteGraph } from '../routes/graph.ts';
 import type { CompiledRouteGraph } from '../routes/types.ts';
 import { parseCommand, type CommandDocument } from './command.ts';
 import { isProjectPathIgnored, readProjectIgnoreRules } from './ignore.ts';
+import { declaredPluginIdentity } from './plugin-identity.ts';
 import { isRenderedSkillSourceName } from './rendered-skill.ts';
 import { parseRule, type RuleDocument } from './rule.ts';
 import { parseSkill, type SkillDocument } from './skill.ts';
@@ -253,6 +255,13 @@ export const discoverProject = async (
 ): Promise<DiscoveredProject> => {
   const projectRoot = resolve(root);
   const rules = await readProjectIgnoreRules(projectRoot);
+  // Rendered skills evaluate during discovery, before normalization stamps
+  // the same identity into the model; `agent-bundle/meta` serves it to them
+  // here so a skill documents the version its plugin ships (#440). A config
+  // without a usable `plugin.name` is the validator's AB4000, not a crash
+  // here, and such a skill gets no identity rather than a fabricated one.
+  const identity = declaredPluginIdentity(projectRoot, config as Readonly<Record<string, unknown>>);
+  const meta = identity === undefined ? undefined : projectMeta(identity);
   const configuredSkills = config.skills;
   const conventionalSources = (await fastGlob('src/skills/*/SKILL.{md,ts,tsx}', {
     absolute: true,
@@ -346,7 +355,7 @@ export const discoverProject = async (
     ...(discoveredRules.length === 0 ? {} : { rules: discoveredRules }),
     ...(shadowedConventionalSkills.length === 0 ? {} : { shadowedConventionalSkills }),
     skills: await Promise.all(
-      skillDirs.map((skillDir) => parseSkill(skillDir, projectRoot, rules)),
+      skillDirs.map((skillDir) => parseSkill(skillDir, projectRoot, rules, meta === undefined ? {} : { meta })),
     ),
     ...(state === undefined ? {} : { state }),
   };

packages/agent-bundle/src/config/normalize.ts

@@ -15,9 +15,9 @@ import {
   parseRuntimeVersion,
   satisfiesGeneratedRuntimeFloor,
 } from '../core/runtime.ts';
-import { developmentFallbackVersion, snapshotPackageIdentity } from '../core/project-context.ts';
 import { isRecord } from '../core/strict-json.ts';
 import { conventionalEntryAt } from './conventional-entry.ts';
+import { pluginIdentity } from './plugin-identity.ts';
 import {
   canonicalHookEvents,
   isPrebuiltEntryInput,
@@ -1201,22 +1201,6 @@ const normalizeRules = (
   };
 });
 
-/**
- * The one plugin version every surface agrees on (issue #94 stage 3): an
- * authored `plugin.version` still wins so a legacy declaration never changes
- * meaning mid-migration (a disagreement with package.json is the AB4008
- * warning), an omitted one derives the release version from package.json,
- * and a project with neither carries the development fallback that
- * `agent-bundle build` refuses to package (AB4013).
- */
-const resolvePluginVersion = (
-  authored: unknown,
-  packageVersion: string | undefined,
-): string =>
-  (typeof authored === 'string' && authored.trim().length > 0 ? authored : undefined)
-  ?? packageVersion
-  ?? developmentFallbackVersion;
-
 /** Selects the generated-executable floor; invalid raises fall back to the default the validator rejected. */
 const normalizeRuntime = (loaded: LoadedConfig): NormalizedRuntime => {
   const node = loaded.config.runtime?.node;
@@ -1272,9 +1256,9 @@ export const normalizeProject = async (
   const logo = normalizePluginLogo(loaded);
   // The npm package axes are derived, never authored in config: package.json
   // is authoritative for release identity (issue #94), while plugin.version
-  // remains the host-facing declared version during the migration.
-  const packageIdentity = snapshotPackageIdentity(loaded.context.projectRoot);
-  const version = resolvePluginVersion(loaded.config.plugin.version, packageIdentity.packageVersion);
+  // remains the host-facing declared version during the migration. The same
+  // derivation serves `agent-bundle/meta` to rendered skills at discovery.
+  const identity = pluginIdentity(loaded.context.projectRoot, loaded.config);
   const hostBins = await normalizeHostBins(loaded, targetNames, registry);
   const hostOutputStyles = await normalizeHostPayloadDirectories(
     loaded,
@@ -1323,11 +1307,11 @@ export const normalizeProject = async (
       ...(typeof description === 'string' ? { description } : {}),
       id: `plugin:${loaded.config.plugin.name}`,
       ...(logo === undefined ? {} : { logo }),
-      name: loaded.config.plugin.name,
-      ...(packageIdentity.packageName === undefined ? {} : { packageName: packageIdentity.packageName }),
-      ...(packageIdentity.packageVersion === undefined ? {} : { packageVersion: packageIdentity.packageVersion }),
+      name: identity.name,
+      ...(identity.packageName === undefined ? {} : { packageName: identity.packageName }),
+      ...(identity.packageVersion === undefined ? {} : { packageVersion: identity.packageVersion }),
       provenance: configProvenance,
-      version,
+      version: identity.version,
     },
     mcpApps: normalizeMcpApps(loaded, discovered, mcpServers),
     mcpServers,

packages/agent-bundle/src/config/plugin-identity.ts

@@ -0,0 +1,61 @@
+import type { ProjectMetaSource } from '../build/meta.ts';
+import { developmentFallbackVersion, snapshotPackageIdentity } from '../core/project-context.ts';
+import { isRecord } from '../core/strict-json.ts';
+import type { AgentBundleConfig } from '../core/types.ts';
+
+/**
+ * The one plugin version every surface agrees on (issue #94 stage 3): an
+ * authored `plugin.version` still wins so a legacy declaration never changes
+ * meaning mid-migration (a disagreement with package.json is the AB4008
+ * warning), an omitted one derives the release version from package.json,
+ * and a project with neither carries the development fallback that
+ * `agent-bundle build` refuses to package (AB4013).
+ */
+export const resolvePluginVersion = (
+  authored: unknown,
+  packageVersion: string | undefined,
+): string =>
+  (typeof authored === 'string' && authored.trim().length > 0 ? authored : undefined)
+  ?? packageVersion
+  ?? developmentFallbackVersion;
+
+/**
+ * The plugin identity axes a project carries before normalization: the
+ * host-native slug from `plugin.name`, the npm axes derived from
+ * `<root>/package.json` (never authored in config), and the resolved plugin
+ * version. `normalizeProject` stamps exactly these into `model.metadata`, and
+ * the rendered-skill loader serves them as `agent-bundle/meta` while
+ * discovery evaluates `SKILL.tsx` — one derivation, so a skill that prints
+ * the plugin version prints the one the artifact manifest reports.
+ */
+export const pluginIdentity = (
+  projectRoot: string,
+  config: Pick<AgentBundleConfig, 'plugin'>,
+): ProjectMetaSource => {
+  const packageIdentity = snapshotPackageIdentity(projectRoot);
+  return Object.freeze({
+    name: config.plugin.name,
+    packageName: packageIdentity.packageName,
+    packageVersion: packageIdentity.packageVersion,
+    version: resolvePluginVersion(config.plugin.version, packageIdentity.packageVersion),
+  });
+};
+
+/**
+ * {@link pluginIdentity} for a configuration that has not been validated yet
+ * (discovery runs before `validateSource`): undefined when `plugin.name` is
+ * not a nonempty string, so a malformed `plugin` block stays the validator's
+ * `AB4000` to report rather than a crash here, and no fabricated identity is
+ * ever served in its place.
+ */
+export const declaredPluginIdentity = (
+  projectRoot: string,
+  config: Readonly<Record<string, unknown>>,
+): ProjectMetaSource | undefined => {
+  const plugin = config.plugin;
+  if (!isRecord(plugin) || typeof plugin.name !== 'string' || plugin.name.trim().length === 0) return undefined;
+  // `resolvePluginVersion` already treats a non-string `version` as absent.
+  return pluginIdentity(projectRoot, {
+    plugin: { name: plugin.name, ...(typeof plugin.version === 'string' ? { version: plugin.version } : {}) },
+  });
+};

packages/agent-bundle/src/config/rendered-skill.ts

@@ -1,12 +1,16 @@
 import { existsSync, statSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { createJiti } from 'jiti';
 import { stringify as stringifyYaml } from 'yaml';
 
+import { generatedMetaModuleSource, metaModuleSpecifier } from '../build/meta.ts';
 import type { Diagnostic } from '../core/diagnostics.ts';
 import { errorMessage } from '../core/errors.ts';
 import { isPlainRecord } from '../core/strict-json.ts';
+import type { AgentBundleMeta } from '../meta.ts';
 import { MarkdownRenderError, renderElementToMarkdown } from './render-markdown.ts';
 
 /**
@@ -52,16 +56,89 @@ const failure = (code: string, message: string, sourcePath: string): RenderedSki
   status: 'failed',
 });
 
+/** What the loader serves to a rendered skill module beyond the project's own code. */
+export interface RenderedSkillLoaderOptions {
+  /**
+   * The project identity `agent-bundle/meta` resolves to while the module
+   * evaluates — the same constants the compiler stamps into every built
+   * surface. Without it the specifier resolves to the published module,
+   * which throws `AB4760` (no compiler, no identity).
+   */
+  readonly meta?: AgentBundleMeta;
+}
+
+/**
+ * The element factory a rendered skill's JSX compiles against. It builds the
+ * plain `{ type, props, key }` objects `renderElementToMarkdown` walks, with
+ * React's fragment symbol, and never touches React: the consumer's `react`
+ * resolves by process condition (`--conditions=react-server` in the
+ * route-unit pool selects the server build) while jiti resolves package
+ * subpaths without those conditions, so binding `react/jsx-runtime` from
+ * one build to `react` from the other throws inside React (#441). The skill
+ * renderer needs no React internals at all, so it does not resolve any.
+ */
+const jsxRuntimeModuleSource = [
+  '// Generated by agent-bundle for one rendered-skill evaluation. Do not edit.',
+  "const elementType = Symbol.for('react.transitional.element');",
+  "export const Fragment = Symbol.for('react.fragment');",
+  'const element = (type, props, key) => ({',
+  '  $$typeof: elementType,',
+  '  key: key === undefined ? null : String(key),',
+  '  props,',
+  '  ref: null,',
+  '  type,',
+  '});',
+  'export const jsx = element;',
+  'export const jsxs = element;',
+  'export const jsxDEV = element;',
+  '',
+].join('\n');
+
+const reactJsxRuntimeSpecifiers = ['react/jsx-runtime', 'react/jsx-dev-runtime'] as const;
+
+/**
+ * Writes the generated modules one evaluation aliases into a private
+ * temporary directory and returns jiti's alias record. Nothing is written
+ * under the project: discovery runs during `validate`, which never touches
+ * the tree it validates.
+ */
+const writeLoaderModules = async (
+  directory: string,
+  options: RenderedSkillLoaderOptions,
+): Promise<Record<string, string>> => {
+  const jsxRuntimePath = join(directory, 'jsx-runtime.mjs');
+  const writes = [writeFile(jsxRuntimePath, jsxRuntimeModuleSource, 'utf8')];
+  const alias: Record<string, string> = Object.fromEntries(
+    reactJsxRuntimeSpecifiers.map((specifier) => [specifier, jsxRuntimePath]),
+  );
+  if (options.meta !== undefined) {
+    const metaPath = join(directory, 'meta.mjs');
+    writes.push(writeFile(metaPath, generatedMetaModuleSource(options.meta), 'utf8'));
+    alias[metaModuleSpecifier] = metaPath;
+  }
+  await Promise.all(writes);
+  return alias;
+};
+
 /**
  * Loads and compiles one rendered skill source to its Markdown document. The
  * module executes through the same jiti pipeline that already runs consumer
- * TypeScript at config-load time, with the automatic JSX runtime resolved
- * from the consumer project.
+ * TypeScript at config-load time. Its JSX compiles against the loader's own
+ * element factory rather than the consumer's `react/jsx-runtime`, and
+ * `agent-bundle/meta` resolves to the project identity when the caller
+ * supplies one; project code the skill imports resolves from the project as
+ * usual.
  */
-export const compileRenderedSkill = async (source: string): Promise<RenderedSkillCompilation> => {
+export const compileRenderedSkill = async (
+  source: string,
+  options: RenderedSkillLoaderOptions = {},
+): Promise<RenderedSkillCompilation> => {
   let moduleExports: Record<string, unknown>;
+  const loaderDirectory = await mkdtemp(join(tmpdir(), 'agent-bundle-rendered-skill-'));
   try {
+    const alias = await writeLoaderModules(loaderDirectory, options);
     const jiti = createJiti(source, {
+      alias,
       interopDefault: true,
       jsx: { runtime: 'automatic' },
       moduleCache: false,
@@ -70,6 +147,8 @@ export const compileRenderedSkill = async (source: string): Promise<RenderedSkil
     moduleExports = await jiti.import<Record<string, unknown>>(source);
   } catch (error) {
     return failure('AB3003', `Rendered Skill module failed to load: ${errorMessage(error)}`, source);
+  } finally {
+    await rm(loaderDirectory, { force: true, recursive: true });
   }
 
   const component = moduleExports.default;

packages/agent-bundle/src/config/skill.ts

@@ -14,10 +14,14 @@ import {
 import {
   compileRenderedSkill,
   isRenderedSkillSourceName,
+  type RenderedSkillLoaderOptions,
   renderedSkillSourceAt,
 } from './rendered-skill.ts';
 import { parseSkillMarkdown } from './skill-references.ts';
 
+/** What a rendered skill module observes while it evaluates; see {@link RenderedSkillLoaderOptions}. */
+export type ParseSkillOptions = RenderedSkillLoaderOptions;
+
 export interface SkillResource {
   bytes: number;
   relativePath: string;
@@ -124,8 +128,9 @@ const parseRenderedSkill = async (
   dir: string,
   renderedSource: string,
   resources: SkillResource[],
+  options: ParseSkillOptions,
 ): Promise<SkillDocument> => {
-  const compiled = await compileRenderedSkill(renderedSource);
+  const compiled = await compileRenderedSkill(renderedSource, options);
   if (compiled.status === 'failed') {
     return {
       body: '',
@@ -158,6 +163,7 @@ export const parseSkill = async (
   projectRoot?: string,
   /** Reuses the caller's compiled ignore rules; discovery parses many skills under one root. */
   projectIgnoreRules?: Ignore,
+  options: ParseSkillOptions = {},
 ): Promise<SkillDocument> => {
   const dir = resolve(skillDir);
   const source = join(dir, 'SKILL.md');
@@ -171,7 +177,7 @@ export const parseSkill = async (
     markdown = await readFile(source, 'utf8');
   } catch (error: unknown) {
     if (renderedSource !== undefined && isErrno(error, 'ENOENT')) {
-      return parseRenderedSkill(dir, renderedSource, resources);
+      return parseRenderedSkill(dir, renderedSource, resources, options);
     }
     return {
       body: '',