@jay-framework/stack-server-runtime 0.11.0 → 0.13.0

package/dist/index.js

@@ -8,7 +8,7 @@ import { notFound, partialRender, phaseOutput, isJayAction } from "@jay-framewor
 import fs$1 from "node:fs/promises";
 import * as path from "node:path";
 import path__default from "node:path";
-import { parseJayFile, JAY_IMPORT_RESOLVER } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, parseAction } from "@jay-framework/compiler-jay-html";
 import { createRequire } from "module";
 import * as fs from "node:fs";
 import { createRequire as createRequire$1 } from "node:module";
@@ -17,6 +17,7 @@ import "js-beautify";
 import fs$2 from "fs";
 import path$1 from "path";
 import YAML from "yaml";
+import { getLogger } from "@jay-framework/logger";
 import crypto from "node:crypto";
 const serviceRegistry = /* @__PURE__ */ new Map();
 function registerService(marker, service) {
@@ -40,9 +41,13 @@ function hasService(marker) {
 function clearServiceRegistry() {
   serviceRegistry.clear();
 }
+function getServiceRegistry() {
+  return serviceRegistry;
+}
 function resolveServices(serviceMarkers) {
   return serviceMarkers.map((marker) => getService(marker));
 }
+globalThis.__JAY_SERVICE_RESOLVER__ = resolveServices;
 const initCallbacks = [];
 const shutdownCallbacks = [];
 function onInit(callback) {
@@ -94,10 +99,17 @@ class DevSlowlyChangingPhase {
   }
   async runSlowlyForPage(pageParams, pageProps, parts) {
     for (const part of parts) {
-      const { compDefinition } = part;
+      const { compDefinition, contractInfo } = part;
       if (compDefinition.loadParams) {
         const services = resolveServices(compDefinition.services);
-        const compParams = compDefinition.loadParams(services);
+        const loadParamsArgs = contractInfo ? [
+          ...services,
+          {
+            contractName: contractInfo.contractName,
+            metadata: contractInfo.metadata
+          }
+        ] : services;
+        const compParams = compDefinition.loadParams(loadParamsArgs);
         if (!await findMatchingParams(pageParams, compParams))
           return notFound();
       }
@@ -105,11 +117,19 @@ class DevSlowlyChangingPhase {
     let slowlyViewState = {};
     let carryForward = {};
     for (const part of parts) {
-      const { compDefinition, key } = part;
+      const { compDefinition, key, contractInfo } = part;
       if (compDefinition.slowlyRender) {
         const services = resolveServices(compDefinition.services);
+        const partProps = {
+          ...pageProps,
+          ...pageParams,
+          ...contractInfo && {
+            contractName: contractInfo.contractName,
+            metadata: contractInfo.metadata
+          }
+        };
         const slowlyRenderedPart = await compDefinition.slowlyRender(
-          { ...pageProps, ...pageParams },
+          partProps,
           ...services
         );
         if (slowlyRenderedPart.kind === "PhaseOutput") {
@@ -136,12 +156,20 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
   let fastViewState = {};
   let fastCarryForward = {};
   for (const part of parts) {
-    const { compDefinition, key } = part;
+    const { compDefinition, key, contractInfo } = part;
     if (compDefinition.fastRender) {
       const partSlowlyCarryForward = key ? carryForward[key] : carryForward;
       const services = resolveServices(compDefinition.services);
+      const partProps = {
+        ...pageProps,
+        ...pageParams,
+        ...contractInfo && {
+          contractName: contractInfo.contractName,
+          metadata: contractInfo.metadata
+        }
+      };
       const fastRenderedPart = await compDefinition.fastRender(
-        { ...pageProps, ...pageParams },
+        partProps,
         partSlowlyCarryForward,
         ...services
       );
@@ -234,13 +262,13 @@ ${clientInitExecution}
       const target = document.getElementById('target');
       const pageComp = makeCompositeJayComponent(render, viewState, fastCarryForward, ${compositeParts}, trackByMap)
 
-      const instance = pageComp({...viewState, ...fastCarryForward})
+      const instance = pageComp({/* placeholder for page props */})
 ${automationWrap}
     <\/script>
   </body>
 </html>`;
 }
-const require$2 = createRequire(import.meta.url);
+const require$3 = createRequire(import.meta.url);
 async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfig, options) {
   const exists = await fs$1.access(route.compPath, fs$1.constants.F_OK).then(() => true).catch(() => false);
   const parts = [];
@@ -268,11 +296,12 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
   );
   return jayHtmlWithValidations.mapAsync(async (jayHtml) => {
     const usedPackages = /* @__PURE__ */ new Set();
+    const headlessInstanceComponents = [];
     for await (const headlessImport of jayHtml.headlessImports) {
       const module = headlessImport.codeLink.module;
       const name = headlessImport.codeLink.names[0].name;
       const isLocalModule = module[0] === "." || module[0] === "/";
-      const modulePath = isLocalModule ? path__default.resolve(dirName, module) : require$2.resolve(module, { paths: require$2.resolve.paths(dirName) });
+      const modulePath = isLocalModule ? path__default.resolve(dirName, module) : require$3.resolve(module, { paths: require$3.resolve.paths(dirName) });
       const compDefinition = (await vite.ssrLoadModule(modulePath))[name];
       const moduleImport = isLocalModule ? path__default.resolve(dirName, module) : module;
       const isNpmPackage = !isLocalModule;
@@ -281,23 +310,101 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
         const packageName = module.startsWith("@") ? module.split("/").slice(0, 2).join("/") : module.split("/")[0];
         usedPackages.add(packageName);
       }
-      const key = headlessImport.key;
-      const part = {
-        key,
-        compDefinition,
-        clientImport: `import {${name}} from '${clientModuleImport}'`,
-        clientPart: `{comp: ${name}.comp, contextMarkers: ${name}.contexts || [], key: '${headlessImport.key}'}`
-      };
-      parts.push(part);
+      if (headlessImport.key) {
+        const key = headlessImport.key;
+        const part = {
+          key,
+          compDefinition,
+          clientImport: `import {${name}} from '${clientModuleImport}'`,
+          clientPart: `{comp: ${name}.comp, contextMarkers: ${name}.contexts || [], key: '${key}'}`,
+          // Include contract info for dynamic contract components
+          contractInfo: headlessImport.contract ? {
+            contractName: headlessImport.contract.name,
+            metadata: headlessImport.metadata
+          } : void 0
+        };
+        parts.push(part);
+      }
+      if (!headlessImport.key && headlessImport.contract) {
+        headlessInstanceComponents.push({
+          contractName: headlessImport.contractName,
+          compDefinition,
+          contract: headlessImport.contract
+        });
+      }
     }
+    const headlessContracts = jayHtml.headlessImports.filter((hi) => hi.contract !== void 0 && hi.key !== void 0).map((hi) => ({
+      key: hi.key,
+      contract: hi.contract,
+      contractPath: hi.contractPath
+    }));
     return {
       parts,
       serverTrackByMap: jayHtml.serverTrackByMap,
       clientTrackByMap: jayHtml.clientTrackByMap,
-      usedPackages
+      usedPackages,
+      headlessContracts,
+      headlessInstanceComponents
     };
   });
 }
+async function slowRenderInstances(discovered, headlessInstanceComponents) {
+  const componentByContractName = /* @__PURE__ */ new Map();
+  for (const comp of headlessInstanceComponents) {
+    componentByContractName.set(comp.contractName, comp);
+  }
+  const resolvedData = [];
+  const slowViewStates = {};
+  const discoveredForFast = [];
+  const carryForwards = {};
+  for (const instance of discovered) {
+    const comp = componentByContractName.get(instance.contractName);
+    if (!comp || !comp.compDefinition.slowlyRender) {
+      continue;
+    }
+    const services = resolveServices(comp.compDefinition.services);
+    const slowResult = await comp.compDefinition.slowlyRender(instance.props, ...services);
+    if (slowResult.kind === "PhaseOutput") {
+      const coordKey = instance.coordinate.join("/");
+      resolvedData.push({
+        coordinate: instance.coordinate,
+        contract: comp.contract,
+        slowViewState: slowResult.rendered
+      });
+      slowViewStates[coordKey] = slowResult.rendered;
+      carryForwards[coordKey] = slowResult.carryForward;
+      discoveredForFast.push({
+        contractName: instance.contractName,
+        props: instance.props,
+        coordinate: instance.coordinate
+      });
+    }
+  }
+  if (discoveredForFast.length === 0) {
+    return void 0;
+  }
+  return {
+    resolvedData,
+    slowViewStates,
+    instancePhaseData: { discovered: discoveredForFast, carryForwards }
+  };
+}
+function validateForEachInstances(forEachInstances, headlessInstanceComponents) {
+  const componentByContractName = /* @__PURE__ */ new Map();
+  for (const comp of headlessInstanceComponents) {
+    componentByContractName.set(comp.contractName, comp);
+  }
+  const validations = [];
+  for (const instance of forEachInstances) {
+    const comp = componentByContractName.get(instance.contractName);
+    if (comp?.compDefinition.slowlyRender) {
+      validations.push(
+        `<jay:${instance.contractName}> inside forEach has a slow rendering phase. Headless components with slow phases cannot be used inside forEach because forEach items are only known at request time, after slow rendering completes. Use slowForEach instead, or remove the slow phase from the component.`
+      );
+    }
+  }
+  return validations;
+}
 class ActionRegistry {
   constructor() {
     __publicField(this, "actions", /* @__PURE__ */ new Map());
@@ -343,6 +450,34 @@ class ActionRegistry {
   getNames() {
     return Array.from(this.actions.keys());
   }
+  /**
+   * Attaches metadata from a .jay-action file to a registered action.
+   * Called during action discovery when a plugin declares action metadata.
+   *
+   * @param actionName - The action name
+   * @param metadata - Parsed ActionMetadata from .jay-action file
+   */
+  setMetadata(actionName, metadata) {
+    const action = this.actions.get(actionName);
+    if (action) {
+      action.metadata = metadata;
+    }
+  }
+  /**
+   * Gets all registered actions that have .jay-action metadata.
+   * These are the actions that should be exposed to AI agents.
+   *
+   * @returns Array of { actionName, metadata } for actions with metadata
+   */
+  getActionsWithMetadata() {
+    const result = [];
+    for (const action of this.actions.values()) {
+      if (action.metadata) {
+        result.push({ actionName: action.actionName, metadata: action.metadata });
+      }
+    }
+    return result;
+  }
   /**
    * Clears all registered actions.
    */
@@ -445,10 +580,6 @@ async function executeAction(actionName, input) {
 function getActionCacheHeaders(actionName) {
   return actionRegistry.getCacheHeaders(actionName);
 }
-async function runAction(action, input) {
-  const services = resolveServices(action.services);
-  return action.handler(input, ...services);
-}
 var __defProp2 = Object.defineProperty;
 var __defNormalProp2 = (obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField2 = (obj, key, value) => {
@@ -478,6 +609,69 @@ new JayObjectType("Error", {
   name: new JayAtomicType("string"),
   stack: new JayAtomicType("string")
 });
+function isOptionalType(aType) {
+  return aType.kind === 13;
+}
+function isAtomicType(aType) {
+  return aType.kind === 0;
+}
+function isEnumType(aType) {
+  return aType.kind === 2;
+}
+function isImportedType(aType) {
+  return aType.kind === 4;
+}
+function isObjectType(aType) {
+  return aType.kind === 8;
+}
+function isArrayType(aType) {
+  return aType.kind === 9;
+}
+function jayTypeToJsonSchema(type) {
+  if (isOptionalType(type)) {
+    return jayTypeToJsonSchema(type.innerType);
+  }
+  if (isAtomicType(type)) {
+    const name = type.name.toLowerCase();
+    if (name === "string" || name === "number" || name === "boolean") {
+      return { type: name };
+    }
+    return { type: "string" };
+  }
+  if (isEnumType(type)) {
+    return { type: "string", enum: type.values };
+  }
+  if (isImportedType(type)) {
+    return { type: "object", description: `Contract: ${type.name}` };
+  }
+  if (isArrayType(type)) {
+    const itemSchema = jayTypeToJsonSchema(type.itemType);
+    if (itemSchema) {
+      return { type: "array", items: itemSchema };
+    }
+    return { type: "array" };
+  }
+  if (isObjectType(type)) {
+    const properties = {};
+    const required = [];
+    for (const [key, propType] of Object.entries(type.props)) {
+      const isOpt = isOptionalType(propType);
+      const schema = jayTypeToJsonSchema(propType);
+      if (schema) {
+        properties[key] = schema;
+        if (!isOpt) {
+          required.push(key);
+        }
+      }
+    }
+    return {
+      type: "object",
+      properties,
+      ...required.length > 0 && { required }
+    };
+  }
+  return null;
+}
 var RuntimeMode = /* @__PURE__ */ ((RuntimeMode2) => {
   RuntimeMode2["MainTrusted"] = "mainTrusted";
   RuntimeMode2["MainSandbox"] = "mainSandbox";
@@ -527,6 +721,12 @@ const JAY_QUERY_PREFIX = "?jay-";
   }
 ];
 createRequire(import.meta.url);
+function normalizeActionEntry(entry) {
+  if (typeof entry === "string") {
+    return { name: entry };
+  }
+  return { name: entry.name, action: entry.action };
+}
 function loadPluginManifest(pluginDir) {
   const pluginYamlPath = path$1.join(pluginDir, "plugin.yaml");
   if (!fs$2.existsSync(pluginYamlPath)) {
@@ -545,7 +745,63 @@ new Proxy(e, {
     return t[r];
   }
 });
-const require$1 = createRequire$1(import.meta.url);
+function parseActionMetadata(yamlContent, fileName) {
+  try {
+    const parsed = parseAction(yamlContent, fileName);
+    if (parsed.validations.length > 0) {
+      getLogger().warn(
+        `[ActionMetadata] ${fileName}: validation errors: ${parsed.validations.join(", ")}`
+      );
+      return null;
+    }
+    if (!parsed.val) {
+      getLogger().warn(`[ActionMetadata] ${fileName}: parsing returned no result`);
+      return null;
+    }
+    const action = parsed.val;
+    const inputJsonSchema = jayTypeToJsonSchema(action.inputType);
+    let inputSchema;
+    if (inputJsonSchema && inputJsonSchema.type === "object") {
+      inputSchema = {
+        type: "object",
+        properties: inputJsonSchema.properties || {},
+        ...inputJsonSchema.required && inputJsonSchema.required.length > 0 && { required: inputJsonSchema.required }
+      };
+    } else {
+      inputSchema = { type: "object", properties: {} };
+    }
+    const metadata = {
+      name: action.name,
+      description: action.description,
+      inputSchema
+    };
+    if (action.outputType) {
+      const outputJsonSchema = jayTypeToJsonSchema(action.outputType);
+      if (outputJsonSchema) {
+        metadata.outputSchema = outputJsonSchema;
+      }
+    }
+    return metadata;
+  } catch (error) {
+    getLogger().error(
+      `[ActionMetadata] Failed to parse ${fileName}: ${error instanceof Error ? error.message : error}`
+    );
+    return null;
+  }
+}
+function loadActionMetadata(filePath) {
+  if (!fs.existsSync(filePath)) {
+    getLogger().warn(`[ActionMetadata] File not found: ${filePath}`);
+    return null;
+  }
+  const yamlContent = fs.readFileSync(filePath, "utf-8");
+  const fileName = path.basename(filePath);
+  return parseActionMetadata(yamlContent, fileName);
+}
+function resolveActionMetadataPath(actionPath, pluginDir) {
+  return path.resolve(pluginDir, actionPath);
+}
+const require$2 = createRequire$1(import.meta.url);
 async function discoverAndRegisterActions(options) {
   const {
     projectRoot,
@@ -562,13 +818,13 @@ async function discoverAndRegisterActions(options) {
   const actionsPath = path.resolve(projectRoot, actionsDir);
   if (!fs.existsSync(actionsPath)) {
     if (verbose) {
-      console.log(`[Actions] No actions directory found at ${actionsPath}`);
+      getLogger().info(`[Actions] No actions directory found at ${actionsPath}`);
     }
     return result;
   }
   const actionFiles = await findActionFiles(actionsPath);
   if (verbose) {
-    console.log(`[Actions] Found ${actionFiles.length} action file(s)`);
+    getLogger().info(`[Actions] Found ${actionFiles.length} action file(s)`);
   }
   for (const filePath of actionFiles) {
     result.scannedFiles.push(filePath);
@@ -585,12 +841,14 @@ async function discoverAndRegisterActions(options) {
           result.actionNames.push(exportValue.actionName);
           result.actionCount++;
           if (verbose) {
-            console.log(`[Actions] Registered: ${exportValue.actionName}`);
+            getLogger().info(
+              `[Actions] Registered: ${exportValue.actionName}`
+            );
           }
         }
       }
     } catch (error) {
-      console.error(`[Actions] Failed to import ${filePath}:`, error);
+      getLogger().error(`[Actions] Failed to import ${filePath}: ${error}`);
     }
   }
   return result;
@@ -657,14 +915,14 @@ async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServ
           continue;
         }
         if (verbose) {
-          console.log(
-            `[Actions] NPM plugin "${packageName}" declares actions:`,
-            pluginConfig.actions
+          getLogger().info(
+            `[Actions] NPM plugin "${packageName}" declares actions: ${JSON.stringify(pluginConfig.actions)}`
           );
         }
         const actions = await registerNpmPluginActions(
           packageName,
           pluginConfig,
+          pluginDir,
           registry,
           verbose,
           viteServer
@@ -675,20 +933,38 @@ async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServ
       }
     }
   } catch (error) {
-    console.error("[Actions] Failed to read project package.json:", error);
+    getLogger().error(`[Actions] Failed to read project package.json: ${error}`);
   }
   return allActions;
 }
 function tryResolvePluginYaml(packageName, projectRoot) {
   try {
-    return require$1.resolve(`${packageName}/plugin.yaml`, {
+    return require$2.resolve(`${packageName}/plugin.yaml`, {
       paths: [projectRoot]
     });
   } catch {
     return null;
   }
 }
-async function registerNpmPluginActions(packageName, pluginConfig, registry, verbose, viteServer) {
+function resolveNpmActionMetadataPath(actionPath, packageName, pluginDir) {
+  if (!actionPath.startsWith(".")) {
+    try {
+      return require$2.resolve(`${packageName}/${actionPath}`, {
+        paths: [pluginDir]
+      });
+    } catch {
+    }
+  }
+  const resolved = resolveActionMetadataPath(actionPath, pluginDir);
+  if (fs.existsSync(resolved)) {
+    return resolved;
+  }
+  getLogger().warn(
+    `[Actions] Could not resolve .jay-action file "${actionPath}" for package "${packageName}"`
+  );
+  return null;
+}
+async function registerNpmPluginActions(packageName, pluginConfig, pluginDir, registry, verbose, viteServer) {
   const registeredActions = [];
   try {
     let pluginModule;
@@ -697,24 +973,42 @@ async function registerNpmPluginActions(packageName, pluginConfig, registry, ver
     } else {
       pluginModule = await import(packageName);
     }
-    for (const actionName of pluginConfig.actions) {
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
       const actionExport = pluginModule[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
-        registeredActions.push(actionExport.actionName);
-        if (verbose) {
-          console.log(
-            `[Actions] Registered NPM plugin action: ${actionExport.actionName}`
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (actionPath) {
+          const metadataFilePath = resolveNpmActionMetadataPath(
+            actionPath,
+            packageName,
+            pluginDir
           );
+          if (metadataFilePath) {
+            const metadata = loadActionMetadata(metadataFilePath);
+            if (metadata) {
+              registry.setMetadata(registeredName, metadata);
+              if (verbose) {
+                getLogger().info(
+                  `[Actions] Loaded metadata for "${registeredName}" from ${actionPath}`
+                );
+              }
+            }
+          }
+        }
+        if (verbose) {
+          getLogger().info(`[Actions] Registered NPM plugin action: ${registeredName}`);
         }
       } else {
-        console.warn(
+        getLogger().warn(
           `[Actions] NPM plugin "${packageName}" declares action "${actionName}" but it's not exported or not a JayAction`
         );
       }
     }
   } catch (importError) {
-    console.error(`[Actions] Failed to import NPM plugin "${packageName}":`, importError);
+    getLogger().error(`[Actions] Failed to import NPM plugin "${packageName}": ${importError}`);
   }
   return registeredActions;
 }
@@ -729,7 +1023,9 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
   const registeredActions = [];
   const pluginName = pluginConfig.name || path.basename(pluginPath);
   if (verbose) {
-    console.log(`[Actions] Plugin "${pluginName}" declares actions:`, pluginConfig.actions);
+    getLogger().info(
+      `[Actions] Plugin "${pluginName}" declares actions: ${JSON.stringify(pluginConfig.actions)}`
+    );
   }
   let modulePath = pluginConfig.module ? path.join(pluginPath, pluginConfig.module) : path.join(pluginPath, "index.ts");
   if (!fs.existsSync(modulePath)) {
@@ -740,7 +1036,7 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
     } else if (fs.existsSync(jsPath)) {
       modulePath = jsPath;
     } else {
-      console.warn(`[Actions] Plugin "${pluginName}" module not found at ${modulePath}`);
+      getLogger().warn(`[Actions] Plugin "${pluginName}" module not found at ${modulePath}`);
       return [];
     }
   }
@@ -751,31 +1047,50 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
     } else {
       pluginModule = await import(modulePath);
     }
-    for (const actionName of pluginConfig.actions) {
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
       const actionExport = pluginModule[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
-        registeredActions.push(actionExport.actionName);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (actionPath) {
+          const metadataFilePath = resolveActionMetadataPath(actionPath, pluginPath);
+          const metadata = loadActionMetadata(metadataFilePath);
+          if (metadata) {
+            registry.setMetadata(registeredName, metadata);
+            if (verbose) {
+              getLogger().info(
+                `[Actions] Loaded metadata for "${registeredName}" from ${actionPath}`
+              );
+            }
+          }
+        }
         if (verbose) {
-          console.log(
-            `[Actions] Registered plugin action: ${actionExport.actionName}`
-          );
+          getLogger().info(`[Actions] Registered plugin action: ${registeredName}`);
         }
       } else {
-        console.warn(
+        getLogger().warn(
           `[Actions] Plugin "${pluginName}" declares action "${actionName}" but it's not exported or not a JayAction`
         );
       }
     }
   } catch (importError) {
-    console.error(`[Actions] Failed to import plugin module at ${modulePath}:`, importError);
+    getLogger().error(
+      `[Actions] Failed to import plugin module at ${modulePath}: ${importError}`
+    );
   }
   return registeredActions;
 }
-const require2 = createRequire$1(import.meta.url);
-async function discoverPluginsWithInit(options) {
-  const { projectRoot, verbose = false } = options;
-  const plugins = [];
+const require$1 = createRequire$1(import.meta.url);
+async function scanPlugins(options) {
+  const {
+    projectRoot,
+    verbose = false,
+    includeDevDeps = false,
+    discoverTransitive = false
+  } = options;
+  const plugins = /* @__PURE__ */ new Map();
   const visitedPackages = /* @__PURE__ */ new Set();
   const localPluginsPath = path.join(projectRoot, "src/plugins");
   if (fs.existsSync(localPluginsPath)) {
@@ -788,37 +1103,37 @@ async function discoverPluginsWithInit(options) {
         const manifest = loadPluginManifest(pluginPath);
         if (!manifest)
           continue;
-        const initConfig = resolvePluginInit(pluginPath, manifest.init, true);
-        if (!initConfig)
-          continue;
         const dependencies = await getPackageDependencies(pluginPath);
-        plugins.push({
-          name: manifest.name || entry.name,
+        const pluginName = manifest.name || entry.name;
+        plugins.set(entry.name, {
+          name: pluginName,
           pluginPath,
           packageName: pluginPath,
-          // For local, use path
+          // For local, use path as identifier
           isLocal: true,
-          initModule: initConfig.module,
-          initExport: initConfig.export,
+          manifest,
           dependencies
         });
         visitedPackages.add(pluginPath);
         if (verbose) {
-          console.log(
-            `[PluginInit] Found local plugin with init: ${manifest.name || entry.name}`
-          );
+          getLogger().info(`[PluginScanner] Found local plugin: ${pluginName}`);
         }
       }
     } catch (error) {
-      console.warn(`[PluginInit] Failed to scan local plugins: ${error}`);
+      if (verbose) {
+        getLogger().warn(`[PluginScanner] Failed to scan local plugins: ${error}`);
+      }
     }
   }
   const projectPackageJsonPath = path.join(projectRoot, "package.json");
   if (fs.existsSync(projectPackageJsonPath)) {
     try {
       const projectPackageJson = JSON.parse(fs.readFileSync(projectPackageJsonPath, "utf-8"));
-      const initialDeps = Object.keys(projectPackageJson.dependencies || {});
-      const packagesToCheck = [...initialDeps];
+      const deps = {
+        ...projectPackageJson.dependencies,
+        ...includeDevDeps ? projectPackageJson.devDependencies : {}
+      };
+      const packagesToCheck = Object.keys(deps);
       while (packagesToCheck.length > 0) {
         const depName = packagesToCheck.shift();
         if (visitedPackages.has(depName))
@@ -826,7 +1141,7 @@ async function discoverPluginsWithInit(options) {
         visitedPackages.add(depName);
         let pluginYamlPath;
         try {
-          pluginYamlPath = require2.resolve(`${depName}/plugin.yaml`, {
+          pluginYamlPath = require$1.resolve(`${depName}/plugin.yaml`, {
             paths: [projectRoot]
           });
         } catch {
@@ -836,30 +1151,77 @@ async function discoverPluginsWithInit(options) {
         const manifest = loadPluginManifest(pluginPath);
         if (!manifest)
           continue;
-        const initConfig = resolvePluginInit(pluginPath, manifest.init, false);
-        if (!initConfig)
-          continue;
         const dependencies = await getPackageDependencies(pluginPath);
-        plugins.push({
+        plugins.set(depName, {
           name: manifest.name || depName,
           pluginPath,
           packageName: depName,
           isLocal: false,
-          initModule: initConfig.module,
-          initExport: initConfig.export,
+          manifest,
           dependencies
         });
         if (verbose) {
-          console.log(`[PluginInit] Found NPM plugin with init: ${depName}`);
+          getLogger().info(`[PluginScanner] Found NPM plugin: ${depName}`);
         }
-        for (const transitiveDep of dependencies) {
-          if (!visitedPackages.has(transitiveDep)) {
-            packagesToCheck.push(transitiveDep);
+        if (discoverTransitive) {
+          for (const transitiveDep of dependencies) {
+            if (!visitedPackages.has(transitiveDep)) {
+              packagesToCheck.push(transitiveDep);
+            }
           }
         }
       }
     } catch (error) {
-      console.warn(`[PluginInit] Failed to scan NPM plugins: ${error}`);
+      if (verbose) {
+        getLogger().warn(`[PluginScanner] Failed to scan NPM plugins: ${error}`);
+      }
+    }
+  }
+  return plugins;
+}
+async function getPackageDependencies(pluginPath) {
+  const packageJsonPath = path.join(pluginPath, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return [];
+  }
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    return Object.keys(packageJson.dependencies || {});
+  } catch {
+    return [];
+  }
+}
+async function discoverPluginsWithInit(options) {
+  const { projectRoot, verbose = false } = options;
+  const scannedPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    includeDevDeps: false,
+    // Only runtime dependencies
+    discoverTransitive: true
+    // Need transitive for dependency ordering
+  });
+  const plugins = [];
+  for (const [key, scanned] of scannedPlugins) {
+    const initConfig = resolvePluginInit(
+      scanned.pluginPath,
+      scanned.manifest.init,
+      scanned.isLocal
+    );
+    if (!initConfig)
+      continue;
+    plugins.push({
+      name: scanned.name,
+      pluginPath: scanned.pluginPath,
+      packageName: scanned.packageName,
+      isLocal: scanned.isLocal,
+      initModule: initConfig.module,
+      initExport: initConfig.export,
+      dependencies: scanned.dependencies,
+      global: scanned.manifest.global === true
+    });
+    if (verbose) {
+      getLogger().info(`[PluginInit] Found plugin with init: ${scanned.name}`);
     }
   }
   return plugins;
@@ -899,18 +1261,6 @@ function resolvePluginInit(pluginPath, initConfig, isLocal) {
     return null;
   }
 }
-async function getPackageDependencies(pluginPath) {
-  const packageJsonPath = path.join(pluginPath, "package.json");
-  if (!fs.existsSync(packageJsonPath)) {
-    return [];
-  }
-  try {
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-    return Object.keys(packageJson.dependencies || {});
-  } catch {
-    return [];
-  }
-}
 function sortPluginsByDependencies(plugins) {
   const pluginNames = new Set(plugins.map((p) => p.packageName));
   const sorted = [];
@@ -920,7 +1270,7 @@ function sortPluginsByDependencies(plugins) {
     if (visited.has(plugin.packageName))
       return;
     if (visiting.has(plugin.packageName)) {
-      console.warn(`[PluginInit] Circular dependency detected for ${plugin.name}`);
+      getLogger().warn(`[PluginInit] Circular dependency detected for ${plugin.name}`);
       return;
     }
     visiting.add(plugin.packageName);
@@ -942,6 +1292,7 @@ function sortPluginsByDependencies(plugins) {
   return sorted;
 }
 async function executePluginServerInits(plugins, viteServer, verbose = false) {
+  const initErrors = /* @__PURE__ */ new Map();
   for (const plugin of plugins) {
     try {
       let modulePath;
@@ -960,14 +1311,14 @@ async function executePluginServerInits(plugins, viteServer, verbose = false) {
       }
       const jayInit = pluginModule[plugin.initExport];
       if (!jayInit || jayInit.__brand !== "JayInit") {
-        console.warn(
+        getLogger().warn(
           `[PluginInit] Plugin "${plugin.name}" init module doesn't export a valid JayInit at "${plugin.initExport}"`
         );
         continue;
       }
       if (typeof jayInit._serverInit === "function") {
         if (verbose) {
-          console.log(`[DevServer] Running server init: ${plugin.name}`);
+          getLogger().info(`[DevServer] Running server init: ${plugin.name}`);
         }
         const clientData = await jayInit._serverInit();
         if (clientData !== void 0 && clientData !== null) {
@@ -975,12 +1326,14 @@ async function executePluginServerInits(plugins, viteServer, verbose = false) {
         }
       }
     } catch (error) {
-      console.error(
-        `[PluginInit] Failed to execute server init for "${plugin.name}":`,
-        error
+      const err = error instanceof Error ? error : new Error(String(error));
+      initErrors.set(plugin.name, err);
+      getLogger().error(
+        `[PluginInit] Failed to execute server init for "${plugin.name}": ${error}`
       );
     }
   }
+  return initErrors;
 }
 function preparePluginClientInits(plugins) {
   return plugins.map((plugin) => {
@@ -1146,6 +1499,509 @@ class SlowRenderCache {
     return Array.from(this.pathToKeys.keys());
   }
 }
+const require2 = createRequire(import.meta.url);
+async function executeDynamicGenerator(plugin, config, projectRoot, services, verbose, viteServer) {
+  const { pluginPath, name: pluginName, isLocal, packageName } = plugin;
+  if (!config.generator) {
+    throw new Error(
+      `Plugin "${pluginName}" has dynamic_contracts entry but no generator specified`
+    );
+  }
+  const isFilePath = config.generator.startsWith("./") || config.generator.startsWith("/") || config.generator.includes(".ts") || config.generator.includes(".js");
+  let generator;
+  if (isFilePath) {
+    let generatorPath;
+    if (!isLocal) {
+      try {
+        generatorPath = require2.resolve(`${packageName}/${config.generator}`, {
+          paths: [projectRoot]
+        });
+      } catch {
+        generatorPath = path.join(pluginPath, config.generator);
+      }
+    } else {
+      generatorPath = path.join(pluginPath, config.generator);
+    }
+    if (!fs.existsSync(generatorPath)) {
+      const withTs = generatorPath + ".ts";
+      const withJs = generatorPath + ".js";
+      if (fs.existsSync(withTs)) {
+        generatorPath = withTs;
+      } else if (fs.existsSync(withJs)) {
+        generatorPath = withJs;
+      }
+    }
+    if (!fs.existsSync(generatorPath)) {
+      throw new Error(
+        `Generator file not found for plugin "${pluginName}": ${config.generator}`
+      );
+    }
+    if (verbose) {
+      getLogger().info(`   Loading generator from file: ${generatorPath}`);
+    }
+    let generatorModule;
+    if (viteServer) {
+      generatorModule = await viteServer.ssrLoadModule(generatorPath);
+    } else {
+      generatorModule = await import(generatorPath);
+    }
+    generator = generatorModule.generator || generatorModule.default;
+  } else {
+    if (verbose) {
+      getLogger().info(
+        `   Loading generator export: ${config.generator} from ${packageName}`
+      );
+    }
+    let pluginModule;
+    if (viteServer) {
+      pluginModule = await viteServer.ssrLoadModule(packageName);
+    } else {
+      pluginModule = await import(packageName);
+    }
+    generator = pluginModule[config.generator];
+    if (!generator) {
+      throw new Error(
+        `Generator "${config.generator}" not exported from plugin "${pluginName}". Ensure it's exported from the package's index.ts`
+      );
+    }
+  }
+  if (!generator || typeof generator.generate !== "function") {
+    throw new Error(
+      `Generator "${config.generator}" for plugin "${pluginName}" must have a 'generate' function. Use makeContractGenerator() to create valid generators.`
+    );
+  }
+  const resolvedServices = [];
+  for (const marker of generator.services) {
+    const service = services.get(marker);
+    if (!service) {
+      const markerName = marker.description ?? "unknown";
+      throw new Error(
+        `Service "${markerName}" required by ${pluginName} generator not found. Ensure it's registered in init.ts`
+      );
+    }
+    resolvedServices.push(service);
+  }
+  if (verbose) {
+    getLogger().info(`   Executing generator...`);
+  }
+  return await generator.generate(...resolvedServices);
+}
+function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
+  const { pluginPath, isLocal, packageName } = plugin;
+  if (!isLocal) {
+    try {
+      return require2.resolve(`${packageName}/${contractSpec}`, {
+        paths: [projectRoot]
+      });
+    } catch {
+      const possiblePaths = [
+        path.join(pluginPath, "dist", contractSpec),
+        path.join(pluginPath, "lib", contractSpec),
+        path.join(pluginPath, contractSpec)
+      ];
+      const found = possiblePaths.find((p) => fs.existsSync(p));
+      return found || possiblePaths[0];
+    }
+  } else {
+    return path.join(pluginPath, contractSpec);
+  }
+}
+function resolveActionFilePath(actionPath, packageName, pluginPath, isLocal, projectRoot) {
+  if (!isLocal && !actionPath.startsWith(".")) {
+    try {
+      return require2.resolve(`${packageName}/${actionPath}`, {
+        paths: [projectRoot]
+      });
+    } catch {
+      const possiblePaths = [
+        path.join(pluginPath, "dist", actionPath),
+        path.join(pluginPath, "lib", actionPath),
+        path.join(pluginPath, actionPath)
+      ];
+      const found = possiblePaths.find((p) => fs.existsSync(p));
+      return found || null;
+    }
+  }
+  const resolved = resolveActionMetadataPath(actionPath, pluginPath);
+  return fs.existsSync(resolved) ? resolved : null;
+}
+function toKebabCase(str) {
+  return str.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
+}
+function getJayStackVersion() {
+  try {
+    const packageJsonPath = path.join(__dirname, "..", "package.json");
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    return packageJson.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function materializeContracts(options, services = /* @__PURE__ */ new Map()) {
+  const {
+    projectRoot,
+    outputDir = path.join(projectRoot, "build", "materialized-contracts"),
+    dynamicOnly = false,
+    pluginFilter,
+    verbose = false,
+    viteServer
+  } = options;
+  const contracts = [];
+  const pluginsIndexMap = /* @__PURE__ */ new Map();
+  let staticCount = 0;
+  let dynamicCount = 0;
+  if (verbose) {
+    getLogger().info("Scanning for plugins...");
+  }
+  const plugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    includeDevDeps: true
+    // Include dev deps for contract discovery
+  });
+  if (verbose) {
+    getLogger().info(`Found ${plugins.size} plugin(s)`);
+  }
+  for (const [pluginKey, plugin] of plugins) {
+    if (pluginFilter && plugin.name !== pluginFilter && pluginKey !== pluginFilter)
+      continue;
+    if (verbose) {
+      getLogger().info(`
+📦 Processing plugin: ${plugin.name}`);
+    }
+    const { manifest } = plugin;
+    if (!dynamicOnly && manifest.contracts) {
+      for (const contract of manifest.contracts) {
+        const contractPath = resolveStaticContractPath(
+          plugin,
+          contract.contract,
+          projectRoot
+        );
+        const relativePath = path.relative(projectRoot, contractPath);
+        const entry = {
+          plugin: plugin.name,
+          name: contract.name,
+          type: "static",
+          path: "./" + relativePath
+        };
+        contracts.push(entry);
+        staticCount++;
+        const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+        if (!pluginsIndexMap.has(plugin.name)) {
+          pluginsIndexMap.set(plugin.name, {
+            path: "./" + pluginRelPath.replace(/\\/g, "/"),
+            contracts: [],
+            actions: []
+          });
+        }
+        pluginsIndexMap.get(plugin.name).contracts.push({
+          name: contract.name,
+          type: "static",
+          path: "./" + relativePath
+        });
+        if (verbose) {
+          getLogger().info(`   📄 Static: ${contract.name}`);
+        }
+      }
+    }
+    if (manifest.dynamic_contracts) {
+      const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+      const pluginOutputDir = path.join(outputDir, plugin.name.replace(/[@/]/g, "_"));
+      fs.mkdirSync(pluginOutputDir, { recursive: true });
+      for (const config of dynamicConfigs) {
+        if (verbose) {
+          getLogger().info(`   ⚡ Dynamic contracts (prefix: ${config.prefix})`);
+        }
+        try {
+          const generatedContracts = await executeDynamicGenerator(
+            plugin,
+            config,
+            projectRoot,
+            services,
+            verbose,
+            viteServer
+          );
+          const prefix = config.prefix;
+          for (const generated of generatedContracts) {
+            const fullName = `${prefix}/${toKebabCase(generated.name)}`;
+            const fileName = `${prefix}-${toKebabCase(generated.name)}.jay-contract`;
+            const filePath = path.join(pluginOutputDir, fileName);
+            fs.writeFileSync(filePath, generated.yaml, "utf-8");
+            const relativePath = path.relative(projectRoot, filePath);
+            const dynEntry = {
+              plugin: plugin.name,
+              name: fullName,
+              type: "dynamic",
+              path: "./" + relativePath,
+              metadata: generated.metadata
+            };
+            contracts.push(dynEntry);
+            dynamicCount++;
+            const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+            if (!pluginsIndexMap.has(plugin.name)) {
+              pluginsIndexMap.set(plugin.name, {
+                path: "./" + pluginRelPath.replace(/\\/g, "/"),
+                contracts: [],
+                actions: []
+              });
+            }
+            pluginsIndexMap.get(plugin.name).contracts.push({
+              name: fullName,
+              type: "dynamic",
+              path: "./" + relativePath
+            });
+            if (verbose) {
+              getLogger().info(`   ⚡ Materialized: ${fullName}`);
+            }
+          }
+        } catch (error) {
+          getLogger().error(
+            `   ❌ Failed to materialize dynamic contracts for ${plugin.name} (${config.prefix}): ${error}`
+          );
+        }
+      }
+    }
+    if (manifest.actions && Array.isArray(manifest.actions)) {
+      for (const entry of manifest.actions) {
+        const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
+        if (!actionPath)
+          continue;
+        const metadataFilePath = resolveActionFilePath(
+          actionPath,
+          plugin.packageName,
+          plugin.pluginPath,
+          plugin.isLocal,
+          projectRoot
+        );
+        if (!metadataFilePath)
+          continue;
+        const metadata = loadActionMetadata(metadataFilePath);
+        if (!metadata)
+          continue;
+        const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+        if (!pluginsIndexMap.has(plugin.name)) {
+          pluginsIndexMap.set(plugin.name, {
+            path: "./" + pluginRelPath.replace(/\\/g, "/"),
+            contracts: [],
+            actions: []
+          });
+        }
+        const actionRelPath = path.relative(projectRoot, metadataFilePath);
+        pluginsIndexMap.get(plugin.name).actions.push({
+          name: metadata.name,
+          description: metadata.description,
+          path: "./" + actionRelPath.replace(/\\/g, "/")
+        });
+        if (verbose) {
+          getLogger().info(`   🔧 Action: ${metadata.name} (${actionPath})`);
+        }
+      }
+    }
+  }
+  const index = {
+    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
+    jay_stack_version: getJayStackVersion(),
+    contracts
+  };
+  fs.mkdirSync(outputDir, { recursive: true });
+  const indexPath = path.join(outputDir, "contracts-index.yaml");
+  fs.writeFileSync(indexPath, YAML.stringify(index), "utf-8");
+  const pluginsIndex = {
+    materialized_at: index.materialized_at,
+    jay_stack_version: index.jay_stack_version,
+    plugins: Array.from(pluginsIndexMap.entries()).map(([name, data]) => ({
+      name,
+      path: data.path,
+      contracts: data.contracts,
+      ...data.actions.length > 0 && { actions: data.actions }
+    }))
+  };
+  const pluginsIndexPath = path.join(outputDir, "plugins-index.yaml");
+  fs.writeFileSync(pluginsIndexPath, YAML.stringify(pluginsIndex), "utf-8");
+  if (verbose) {
+    getLogger().info(`
+✅ Contracts index written to: ${indexPath}`);
+    getLogger().info(`✅ Plugins index written to: ${pluginsIndexPath}`);
+  }
+  return {
+    index,
+    staticCount,
+    dynamicCount,
+    outputDir
+  };
+}
+async function listContracts(options) {
+  const { projectRoot, dynamicOnly = false, pluginFilter } = options;
+  const contracts = [];
+  const plugins = await scanPlugins({
+    projectRoot,
+    includeDevDeps: true
+  });
+  for (const [pluginKey, plugin] of plugins) {
+    if (pluginFilter && plugin.name !== pluginFilter && pluginKey !== pluginFilter)
+      continue;
+    const { manifest } = plugin;
+    if (!dynamicOnly && manifest.contracts) {
+      for (const contract of manifest.contracts) {
+        const contractPath = resolveStaticContractPath(
+          plugin,
+          contract.contract,
+          projectRoot
+        );
+        const relativePath = path.relative(projectRoot, contractPath);
+        contracts.push({
+          plugin: plugin.name,
+          name: contract.name,
+          type: "static",
+          path: "./" + relativePath
+        });
+      }
+    }
+    if (manifest.dynamic_contracts) {
+      const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+      for (const config of dynamicConfigs) {
+        contracts.push({
+          plugin: plugin.name,
+          name: `${config.prefix}/*`,
+          type: "dynamic",
+          path: "(run materialization to generate)"
+        });
+      }
+    }
+  }
+  return {
+    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
+    jay_stack_version: getJayStackVersion(),
+    contracts
+  };
+}
+async function discoverPluginsWithSetup(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    discoverTransitive: true
+  });
+  const pluginsWithSetup = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.setup?.handler)
+      continue;
+    if (pluginFilter && plugin.name !== pluginFilter && packageName !== pluginFilter) {
+      continue;
+    }
+    pluginsWithSetup.push({
+      name: plugin.name,
+      pluginPath: plugin.pluginPath,
+      packageName: plugin.packageName,
+      isLocal: plugin.isLocal,
+      setupHandler: plugin.manifest.setup.handler,
+      setupDescription: plugin.manifest.setup.description,
+      dependencies: plugin.dependencies
+    });
+    if (verbose) {
+      getLogger().info(`[Setup] Found plugin with setup: ${plugin.name}`);
+    }
+  }
+  return sortByDependencies(pluginsWithSetup);
+}
+async function discoverPluginsWithReferences(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    discoverTransitive: true
+  });
+  const pluginsWithRefs = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.setup?.references)
+      continue;
+    if (pluginFilter && plugin.name !== pluginFilter && packageName !== pluginFilter) {
+      continue;
+    }
+    pluginsWithRefs.push({
+      name: plugin.name,
+      pluginPath: plugin.pluginPath,
+      packageName: plugin.packageName,
+      isLocal: plugin.isLocal,
+      referencesHandler: plugin.manifest.setup.references,
+      dependencies: plugin.dependencies
+    });
+    if (verbose) {
+      getLogger().info(`[AgentKit] Found plugin with references: ${plugin.name}`);
+    }
+  }
+  return sortByDependencies(pluginsWithRefs);
+}
+function sortByDependencies(plugins) {
+  return [...plugins].sort((a, b) => {
+    const aDepsOnB = a.dependencies.some((d) => d === b.name || d === b.packageName) ? 1 : 0;
+    const bDepsOnA = b.dependencies.some((d) => d === a.name || d === a.packageName) ? 1 : 0;
+    return aDepsOnB - bDepsOnA;
+  });
+}
+async function executePluginSetup(plugin, options) {
+  const { projectRoot, configDir, force, initError, viteServer, verbose } = options;
+  const context = {
+    pluginName: plugin.name,
+    projectRoot,
+    configDir,
+    services: getServiceRegistry(),
+    initError,
+    force
+  };
+  const handler = await loadHandler(plugin, plugin.setupHandler, viteServer);
+  return handler(context);
+}
+async function executePluginReferences(plugin, options) {
+  const { projectRoot, force, initError, viteServer } = options;
+  const referencesDir = path.join(projectRoot, "agent-kit", "references", plugin.name);
+  const context = {
+    pluginName: plugin.name,
+    projectRoot,
+    referencesDir,
+    services: getServiceRegistry(),
+    initError,
+    force
+  };
+  const handler = await loadHandler(
+    plugin,
+    plugin.referencesHandler,
+    viteServer
+  );
+  return handler(context);
+}
+async function loadHandler(plugin, handlerName, viteServer) {
+  let module;
+  if (plugin.isLocal) {
+    const handlerPath = path.resolve(plugin.pluginPath, handlerName);
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(handlerPath);
+    } else {
+      module = await import(handlerPath);
+    }
+    if (typeof module[handlerName] === "function")
+      return module[handlerName];
+    if (typeof module.setup === "function")
+      return module.setup;
+    if (typeof module.default === "function")
+      return module.default;
+    throw new Error(
+      `Handler "${handlerName}" not found in "${plugin.pluginPath}". Available exports: ${Object.keys(module).join(", ")}`
+    );
+  } else {
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(plugin.packageName);
+    } else {
+      module = await import(plugin.packageName);
+    }
+    if (typeof module[handlerName] !== "function") {
+      throw new Error(
+        `Handler "${handlerName}" not found as export in "${plugin.packageName}". Available exports: ${Object.keys(module).join(", ")}`
+      );
+    }
+    return module[handlerName];
+  }
+}
 export {
   ActionRegistry,
   DevSlowlyChangingPhase,
@@ -1159,8 +2015,12 @@ export {
   discoverAndRegisterActions,
   discoverPluginActions,
   discoverPluginsWithInit,
+  discoverPluginsWithReferences,
+  discoverPluginsWithSetup,
   executeAction,
+  executePluginReferences,
   executePluginServerInits,
+  executePluginSetup,
   generateClientScript,
   getActionCacheHeaders,
   getClientInitData,
@@ -1168,21 +2028,29 @@ export {
   getRegisteredAction,
   getRegisteredActionNames,
   getService,
+  getServiceRegistry,
   hasAction,
   hasService,
+  listContracts,
+  loadActionMetadata,
   loadPageParts,
+  materializeContracts,
   onInit,
   onShutdown,
+  parseActionMetadata,
   preparePluginClientInits,
   registerAction,
   registerService,
   renderFastChangingData,
+  resolveActionMetadataPath,
   resolveServices,
-  runAction,
   runInitCallbacks,
   runLoadParams,
   runShutdownCallbacks,
   runSlowlyChangingRender,
+  scanPlugins,
   setClientInitData,
-  sortPluginsByDependencies
+  slowRenderInstances,
+  sortPluginsByDependencies,
+  validateForEachInstances
 };