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

package/dist/index.d.ts

@@ -2,8 +2,10 @@ import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlPa
 import { JayComponentCore } from '@jay-framework/component';
 import { ViteDevServer } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
-import { WithValidations, PluginManifest } from '@jay-framework/compiler-shared';
-import { Contract, HeadlessContractInfo, DiscoveredHeadlessInstance } from '@jay-framework/compiler-jay-html';
+import { WithValidations, JsonSchemaProperty, PluginManifest } from '@jay-framework/compiler-shared';
+export { JsonSchemaProperty } from '@jay-framework/compiler-shared';
+import { Contract, HeadlessContractInfo, ForEachHeadlessInstance, DiscoveredHeadlessInstance } from '@jay-framework/compiler-jay-html';
+export { ForEachHeadlessInstance } from '@jay-framework/compiler-jay-html';
 import { JayRollupConfig } from '@jay-framework/rollup-plugin';
 import { TrackByMap } from '@jay-framework/view-state-merge';
 import { Coordinate } from '@jay-framework/runtime';
@@ -67,6 +69,50 @@ declare function runSlowlyChangingRender<Refs extends object, SlowVS extends obj
 
 declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>): Promise<AnyFastRenderResult>;
 
+/**
+ * Action metadata loaded from .jay-action files.
+ *
+ * Uses the compiler's parseAction to parse .jay-action YAML into JayType,
+ * then converts JayType → JSON Schema for consumers (AI agent tool builders).
+ *
+ * Actions without .jay-action files are not exposed to AI agents.
+ */
+
+/**
+ * Input schema for an action (JSON Schema object type).
+ */
+interface ActionSchema {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+/**
+ * Metadata loaded from a .jay-action file.
+ */
+interface ActionMetadata {
+    /** Action name (must match the export name in plugin code) */
+    name: string;
+    /** Human-readable description of what the action does */
+    description: string;
+    /** JSON Schema for the action's input parameters */
+    inputSchema: ActionSchema;
+    /** JSON Schema for the action's output (optional) */
+    outputSchema?: JsonSchemaProperty;
+}
+/**
+ * Parses a .jay-action YAML string into ActionMetadata.
+ * Uses the compiler's parseAction to produce JayType, then converts to JSON Schema.
+ */
+declare function parseActionMetadata(yamlContent: string, fileName: string): ActionMetadata | null;
+/**
+ * Loads action metadata from a .jay-action file on disk.
+ */
+declare function loadActionMetadata(filePath: string): ActionMetadata | null;
+/**
+ * Resolves the absolute path of a .jay-action file relative to a plugin directory.
+ */
+declare function resolveActionMetadataPath(actionPath: string, pluginDir: string): string;
+
 /**
  * Action registry for Jay Stack server-side action handling.
  *
@@ -88,6 +134,9 @@ interface RegisteredAction {
     services: any[];
     /** The handler function */
     handler: (input: any, ...services: any[]) => Promise<any>;
+    /** Optional metadata from .jay-action file (description, input/output schemas).
+     *  Actions with metadata are exposed to AI agents; those without are not. */
+    metadata?: ActionMetadata;
 }
 /**
  * Result of executing an action.
@@ -153,6 +202,24 @@ declare class ActionRegistry {
      * @returns Array of registered action names
      */
     getNames(): string[];
+    /**
+     * 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: string, metadata: ActionMetadata): void;
+    /**
+     * 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(): Array<{
+        actionName: string;
+        metadata: ActionMetadata;
+    }>;
     /**
      * Clears all registered actions.
      */
@@ -346,6 +413,8 @@ interface PluginWithInit {
     initExport: string;
     /** Dependencies from package.json (for ordering) */
     dependencies: string[];
+    /** When true, plugin is loaded on every page regardless of usage in jay-html */
+    global: boolean;
 }
 /**
  * Options for plugin init discovery.
@@ -383,7 +452,7 @@ declare function sortPluginsByDependencies(plugins: PluginWithInit[]): PluginWit
  * @param viteServer - Vite server for SSR module loading (optional)
  * @param verbose - Whether to log progress
  */
-declare function executePluginServerInits(plugins: PluginWithInit[], viteServer?: ViteSSRLoader, verbose?: boolean): Promise<void>;
+declare function executePluginServerInits(plugins: PluginWithInit[], viteServer?: ViteSSRLoader, verbose?: boolean): Promise<Map<string, Error>>;
 /**
  * Information needed to generate client init script for a plugin.
  */
@@ -621,6 +690,8 @@ interface InstancePhaseData {
     }>;
     /** CarryForward per instance (keyed by coordinate path, e.g. "p1/product-card:0") */
     carryForwards: Record<string, object>;
+    /** ForEach instances that need fast-phase per-item rendering */
+    forEachInstances?: ForEachHeadlessInstance[];
 }
 /**
  * Result of running slowlyRender for all discovered headless instances.
@@ -643,6 +714,15 @@ interface InstanceSlowRenderResult {
  * Shared between preRenderJayHtml (pre-render path) and handleDirectRequest (direct path).
  */
 declare function slowRenderInstances(discovered: DiscoveredHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): Promise<InstanceSlowRenderResult | undefined>;
+/**
+ * Validate that forEach headless instances do not have a slow phase.
+ *
+ * Components with slowlyRender cannot be used inside forEach because
+ * forEach items are only known at request time, after slow rendering completes.
+ *
+ * @returns Array of validation error messages (empty if all valid)
+ */
+declare function validateForEachInstances(forEachInstances: ForEachHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): string[];
 
 /**
  * Cache entry for pre-rendered jay-html
@@ -744,6 +824,13 @@ interface ContractsIndex {
     jay_stack_version: string;
     contracts: ContractIndexEntry[];
 }
+/** Action metadata entry in plugins-index.yaml */
+interface ActionIndexEntry {
+    name: string;
+    description: string;
+    /** Path to the .jay-action file (relative to project root) */
+    path: string;
+}
 /** Entry for plugins-index.yaml (Design Log #85) */
 interface PluginsIndexEntry {
     name: string;
@@ -753,6 +840,8 @@ interface PluginsIndexEntry {
         type: 'static' | 'dynamic';
         path: string;
     }>;
+    /** Actions with .jay-action metadata (exposed to AI agents) */
+    actions?: ActionIndexEntry[];
 }
 interface PluginsIndex {
     materialized_at: string;
@@ -887,7 +976,7 @@ interface PluginSetupResult {
 type PluginSetupHandler = (context: PluginSetupContext) => Promise<PluginSetupResult>;
 /**
  * Context passed to a plugin's references handler.
- * Services are guaranteed to be initialized (agent-kit already does this).
+ * Services may or may not be initialized — check initError if your handler needs them.
  */
 interface PluginReferencesContext {
     /** Plugin name (from plugin.yaml) */
@@ -898,6 +987,8 @@ interface PluginReferencesContext {
     referencesDir: string;
     /** Registered services */
     services: Map<symbol, unknown>;
+    /** Present if this plugin's server init failed */
+    initError?: Error;
     /** Whether --force flag was passed */
     force: boolean;
 }
@@ -981,8 +1072,9 @@ declare function executePluginSetup(plugin: PluginWithSetup, options: {
 declare function executePluginReferences(plugin: PluginWithReferences, options: {
     projectRoot: string;
     force: boolean;
+    initError?: Error;
     viteServer?: ViteSSRLoader;
     verbose?: boolean;
 }): Promise<PluginReferencesResult>;
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, ActionRegistry, type ContractIndexEntry, type ContractsIndex, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type ScannedPlugin, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, listContracts, loadPageParts, materializeContracts, onInit, onShutdown, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies };
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type ContractIndexEntry, type ContractsIndex, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type ScannedPlugin, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, listContracts, loadActionMetadata, loadPageParts, materializeContracts, onInit, onShutdown, parseActionMetadata, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies, validateForEachInstances };

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";
@@ -389,6 +389,22 @@ async function slowRenderInstances(discovered, headlessInstanceComponents) {
     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());
@@ -434,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.
    */
@@ -565,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";
@@ -614,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)) {
@@ -632,6 +745,62 @@ new Proxy(e, {
     return t[r];
   }
 });
+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 {
@@ -753,6 +922,7 @@ async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServ
         const actions = await registerNpmPluginActions(
           packageName,
           pluginConfig,
+          pluginDir,
           registry,
           verbose,
           viteServer
@@ -776,7 +946,25 @@ function tryResolvePluginYaml(packageName, projectRoot) {
     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;
@@ -785,15 +973,33 @@ 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) {
-          getLogger().info(
-            `[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 {
         getLogger().warn(
@@ -841,15 +1047,27 @@ 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) {
-          getLogger().info(
-            `[Actions] Registered plugin action: ${actionExport.actionName}`
-          );
+          getLogger().info(`[Actions] Registered plugin action: ${registeredName}`);
         }
       } else {
         getLogger().warn(
@@ -999,7 +1217,8 @@ async function discoverPluginsWithInit(options) {
       isLocal: scanned.isLocal,
       initModule: initConfig.module,
       initExport: initConfig.export,
-      dependencies: scanned.dependencies
+      dependencies: scanned.dependencies,
+      global: scanned.manifest.global === true
     });
     if (verbose) {
       getLogger().info(`[PluginInit] Found plugin with init: ${scanned.name}`);
@@ -1073,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;
@@ -1106,11 +1326,14 @@ async function executePluginServerInits(plugins, viteServer, verbose = false) {
         }
       }
     } catch (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) => {
@@ -1361,8 +1584,7 @@ async function executeDynamicGenerator(plugin, config, projectRoot, services, ve
   if (verbose) {
     getLogger().info(`   Executing generator...`);
   }
-  const result = await generator.generate(...resolvedServices);
-  return result;
+  return await generator.generate(...resolvedServices);
 }
 function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
   const { pluginPath, isLocal, packageName } = plugin;
@@ -1384,6 +1606,25 @@ function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
     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(/^-/, "");
 }
@@ -1449,7 +1690,8 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
         if (!pluginsIndexMap.has(plugin.name)) {
           pluginsIndexMap.set(plugin.name, {
             path: "./" + pluginRelPath.replace(/\\/g, "/"),
-            contracts: []
+            contracts: [],
+            actions: []
           });
         }
         pluginsIndexMap.get(plugin.name).contracts.push({
@@ -1499,7 +1741,8 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
             if (!pluginsIndexMap.has(plugin.name)) {
               pluginsIndexMap.set(plugin.name, {
                 path: "./" + pluginRelPath.replace(/\\/g, "/"),
-                contracts: []
+                contracts: [],
+                actions: []
               });
             }
             pluginsIndexMap.get(plugin.name).contracts.push({
@@ -1518,6 +1761,42 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
         }
       }
     }
+    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(),
@@ -1533,7 +1812,8 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
     plugins: Array.from(pluginsIndexMap.entries()).map(([name, data]) => ({
       name,
       path: data.path,
-      contracts: data.contracts
+      contracts: data.contracts,
+      ...data.actions.length > 0 && { actions: data.actions }
     }))
   };
   const pluginsIndexPath = path.join(outputDir, "plugins-index.yaml");
@@ -1673,13 +1953,14 @@ async function executePluginSetup(plugin, options) {
   return handler(context);
 }
 async function executePluginReferences(plugin, options) {
-  const { projectRoot, force, viteServer } = 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(
@@ -1751,14 +2032,17 @@ export {
   hasAction,
   hasService,
   listContracts,
+  loadActionMetadata,
   loadPageParts,
   materializeContracts,
   onInit,
   onShutdown,
+  parseActionMetadata,
   preparePluginClientInits,
   registerAction,
   registerService,
   renderFastChangingData,
+  resolveActionMetadataPath,
   resolveServices,
   runInitCallbacks,
   runLoadParams,
@@ -1767,5 +2051,6 @@ export {
   scanPlugins,
   setClientInitData,
   slowRenderInstances,
-  sortPluginsByDependencies
+  sortPluginsByDependencies,
+  validateForEachInstances
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-server-runtime",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.mts",
@@ -26,20 +26,20 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.12.0",
-    "@jay-framework/compiler-shared": "^0.12.0",
-    "@jay-framework/component": "^0.12.0",
-    "@jay-framework/fullstack-component": "^0.12.0",
-    "@jay-framework/logger": "^0.12.0",
-    "@jay-framework/runtime": "^0.12.0",
-    "@jay-framework/stack-route-scanner": "^0.12.0",
-    "@jay-framework/view-state-merge": "^0.12.0",
+    "@jay-framework/compiler-jay-html": "^0.13.0",
+    "@jay-framework/compiler-shared": "^0.13.0",
+    "@jay-framework/component": "^0.13.0",
+    "@jay-framework/fullstack-component": "^0.13.0",
+    "@jay-framework/logger": "^0.13.0",
+    "@jay-framework/runtime": "^0.13.0",
+    "@jay-framework/stack-route-scanner": "^0.13.0",
+    "@jay-framework/view-state-merge": "^0.13.0",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.12.0",
-    "@jay-framework/jay-cli": "^0.12.0",
-    "@jay-framework/stack-client-runtime": "^0.12.0",
+    "@jay-framework/dev-environment": "^0.13.0",
+    "@jay-framework/jay-cli": "^0.13.0",
+    "@jay-framework/stack-client-runtime": "^0.13.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",