Merge pull request #284 from chubes4/fix/runtime-mu-plugin-load-mode

fix: load runtime recipe plugins as mu-plugins

Author: chubes4

README.md

@@ -521,6 +521,8 @@ Dry-run output uses `wp-codebox/recipe-run-dry-run/v1` and includes resolved mou
 
 `inputs.extra_plugins` accepts existing local plugin directory paths and external HTTPS zip sources. Local paths keep the existing behavior: they are resolved relative to the recipe file and mounted read-only under `/wordpress/wp-content/plugins/<slug>`.
 
+Set `loadAs` to `mu-plugin` for runtime substrate that should load as must-use infrastructure instead of appearing as a normal user-managed plugin. WP Codebox mounts those plugins under `/wordpress/wp-content/mu-plugins/wp-codebox-runtime/<slug>` and writes a `wp-codebox-runtime-loader.php` setup loader. Use this for sandbox/runtime plumbing such as Agents API, Data Machine, Data Machine Code, and AI provider bridges. Leave user-visible site plugins as the default `plugin` load mode.
+
 External sources are explicit and CI-safe. WP Codebox validates URL-shaped sources before Playground boots, but it downloads them only when `WP_CODEBOX_ALLOW_NETWORK_DOWNLOADS=1` is set. Supported first-slice forms are WordPress.org plugin zip URLs and generic HTTPS `.zip` URLs:
 
 ```json
@@ -536,6 +538,13 @@ External sources are explicit and CI-safe. WP Codebox validates URL-shaped sourc
         "source": "https://example.com/acme-helper.zip",
         "slug": "acme-helper",
         "pluginFile": "acme-helper/acme-helper.php"
+      },
+      {
+        "source": "../agents-api",
+        "slug": "agents-api",
+        "pluginFile": "agents-api/agents-api.php",
+        "activate": false,
+        "loadAs": "mu-plugin"
       }
     ]
   }

packages/cli/src/agent-code.ts

@@ -406,6 +406,22 @@ $plugins = array_merge(array(
     'data-machine-code/data-machine-code.php',
 ), wp_codebox_provider_plugin_entries(json_decode(${JSON.stringify(JSON.stringify(providerPlugins))}, true)));
 
+function wp_codebox_plugin_entry_path(string $plugin): ?array {
+    $plugin = ltrim($plugin, '/');
+    if ('' === $plugin || str_contains($plugin, '..') || !str_ends_with($plugin, '.php')) {
+        return null;
+    }
+    $normal_path = WP_PLUGIN_DIR . '/' . $plugin;
+    if (file_exists($normal_path)) {
+        return array('path' => $normal_path, 'load_as' => 'plugin');
+    }
+    $mu_path = WPMU_PLUGIN_DIR . '/wp-codebox-runtime/' . $plugin;
+    if (file_exists($mu_path)) {
+        return array('path' => $mu_path, 'load_as' => 'mu-plugin');
+    }
+    return null;
+}
+
 function wp_codebox_provider_plugin_entries(array $provider_plugins): array {
     $entries = array();
     foreach ($provider_plugins as $plugin) {
@@ -415,7 +431,7 @@ function wp_codebox_provider_plugin_entries(array $provider_plugins): array {
         }
         $candidates = array($slug . '/plugin.php', $slug . '/' . $slug . '.php');
         foreach ($candidates as $candidate) {
-            if (file_exists(WP_PLUGIN_DIR . '/' . $candidate)) {
+            if (wp_codebox_plugin_entry_path($candidate)) {
                 $entries[] = $candidate;
                 break;
             }
@@ -427,9 +443,20 @@ function wp_codebox_provider_plugin_entries(array $provider_plugins): array {
 $activation_results = array();
 
 foreach ($plugins as $plugin) {
-    $result = activate_plugin($plugin);
+    $entry = wp_codebox_plugin_entry_path($plugin);
+    if (!$entry) {
+        $activation_results[$plugin] = array('active' => false, 'error' => 'Plugin is not mounted.');
+        continue;
+    }
+    $result = null;
+    if ('mu-plugin' === $entry['load_as']) {
+        require_once $entry['path'];
+    } else {
+        $result = activate_plugin($plugin);
+    }
     $activation_results[$plugin] = array(
-        'active' => is_plugin_active($plugin),
+        'active' => 'mu-plugin' === $entry['load_as'] ? true : is_plugin_active($plugin),
+        'load_as' => $entry['load_as'],
         'error' => is_wp_error($result) ? $result->get_error_message() : null,
     );
 }
@@ -491,6 +518,22 @@ $plugins = array_merge(array(
     'data-machine-code/data-machine-code.php',
 ), wp_codebox_provider_plugin_entries(json_decode(${JSON.stringify(JSON.stringify(providerPlugins))}, true)));
 
+function wp_codebox_plugin_entry_path(string $plugin): ?array {
+    $plugin = ltrim($plugin, '/');
+    if ('' === $plugin || str_contains($plugin, '..') || !str_ends_with($plugin, '.php')) {
+        return null;
+    }
+    $normal_path = WP_PLUGIN_DIR . '/' . $plugin;
+    if (file_exists($normal_path)) {
+        return array('path' => $normal_path, 'load_as' => 'plugin');
+    }
+    $mu_path = WPMU_PLUGIN_DIR . '/wp-codebox-runtime/' . $plugin;
+    if (file_exists($mu_path)) {
+        return array('path' => $mu_path, 'load_as' => 'mu-plugin');
+    }
+    return null;
+}
+
 function wp_codebox_provider_plugin_entries(array $provider_plugins): array {
     $entries = array();
     foreach ($provider_plugins as $plugin) {
@@ -500,7 +543,7 @@ function wp_codebox_provider_plugin_entries(array $provider_plugins): array {
         }
         $candidates = array($slug . '/plugin.php', $slug . '/' . $slug . '.php');
         foreach ($candidates as $candidate) {
-            if (file_exists(WP_PLUGIN_DIR . '/' . $candidate)) {
+            if (wp_codebox_plugin_entry_path($candidate)) {
                 $entries[] = $candidate;
                 break;
             }
@@ -512,9 +555,20 @@ function wp_codebox_provider_plugin_entries(array $provider_plugins): array {
 $activation_results = array();
 
 foreach ($plugins as $plugin) {
-    $result = activate_plugin($plugin);
+    $entry = wp_codebox_plugin_entry_path($plugin);
+    if (!$entry) {
+        $activation_results[$plugin] = array('active' => false, 'error' => 'Plugin is not mounted.');
+        continue;
+    }
+    $result = null;
+    if ('mu-plugin' === $entry['load_as']) {
+        require_once $entry['path'];
+    } else {
+        $result = activate_plugin($plugin);
+    }
     $activation_results[$plugin] = array(
-        'active' => is_plugin_active($plugin),
+        'active' => 'mu-plugin' === $entry['load_as'] ? true : is_plugin_active($plugin),
+        'load_as' => $entry['load_as'],
         'error' => is_wp_error($result) ? $result->get_error_message() : null,
     );
 }

packages/cli/src/index.ts

@@ -426,6 +426,7 @@ interface RecipeDryRunExtraPlugin {
   target: string
   pluginFile: string
   activate: boolean
+  loadAs: "plugin" | "mu-plugin"
   provenance: RecipeSourceProvenance
 }
 
@@ -534,6 +535,7 @@ interface PreparedExtraPlugin {
   target: string
   pluginFile: string
   activate: boolean
+  loadAs: "plugin" | "mu-plugin"
   cleanupPaths: string[]
   provenance: RecipeSourceProvenance
 }
@@ -1428,6 +1430,11 @@ async function runRecipe(options: RecipeRunOptions, interruption?: RecipeInterru
       interruption?.throwIfInterrupted()
     }
 
+    const muPluginInstallCode = installMuPluginsCode(extraPlugins)
+    if (muPluginInstallCode) {
+      executions.push(withRecipeExecutionPhase(await runtime.execute({ command: "wordpress.run-php", args: [`code=${muPluginInstallCode}`] }), "setup", -2))
+    }
+
     const pluginActivationCode = activateExtraPluginsCode(extraPlugins)
     if (pluginActivationCode) {
       executions.push(withRecipeExecutionPhase(await awaitRecipe(runtime.execute({ command: "wordpress.run-php", args: [`code=${pluginActivationCode}`] })), "setup", -1))
@@ -3247,6 +3254,10 @@ function parseWorkspaceRecipe(raw: string, recipePath: string): WorkspaceRecipe
     if (plugin.slug && !/^[a-z0-9][a-z0-9-_]*$/i.test(plugin.slug)) {
       throw new Error(`Recipe extra_plugins slug must be a plugin-directory slug: ${recipePath}`)
     }
+
+    if (plugin.loadAs && plugin.loadAs !== "plugin" && plugin.loadAs !== "mu-plugin") {
+      throw new Error(`Recipe extra_plugins loadAs must be plugin or mu-plugin: ${recipePath}`)
+    }
   }
 
   const siteSeeds = recipe.inputs?.siteSeeds ?? []
@@ -3639,13 +3650,18 @@ async function recipeDryRunSteps(recipe: WorkspaceRecipe, recipeDirectory: strin
     return {
       source: plugin.source,
       slug,
-      target: `/wordpress/wp-content/plugins/${slug}`,
+      target: pluginTarget(slug, plugin.loadAs ?? "plugin"),
       pluginFile: await resolveRecipeExtraPluginFile(plugin, recipeDirectory),
       activate: plugin.activate !== false,
+      loadAs: plugin.loadAs ?? "plugin",
       cleanupPaths: [],
       provenance: recipeSourceProvenance(recipeSource(plugin.source, plugin.sha256), recipeDirectory),
     }
   }))
+  const muPluginInstallCode = installMuPluginsCode(dryRunExtraPlugins)
+  if (muPluginInstallCode) {
+    steps.push(recipeDryRunStep({ command: "wordpress.run-php", args: [`code=${muPluginInstallCode}`] }, recipeDirectory, policy, "setup", -2, "install-mu-plugins"))
+  }
   const pluginActivationCode = activateExtraPluginsCode(dryRunExtraPlugins)
   if (pluginActivationCode) {
     steps.push(recipeDryRunStep({ command: "wordpress.run-php", args: [`code=${pluginActivationCode}`] }, recipeDirectory, policy, "setup", -1, "activate-extra-plugins"))
@@ -3725,8 +3741,10 @@ function recipeRunMetadata(recipe: WorkspaceRecipe, recipePath: string, workspac
   const extraPluginMetadata = extraPlugins.map((plugin) => ({
     source: plugin.source,
     slug: plugin.slug,
+    target: plugin.target,
     pluginFile: plugin.pluginFile,
     activate: plugin.activate,
+    loadAs: plugin.loadAs,
     provenance: plugin.provenance,
   }))
   const siteSeedProvenance = recipeDryRunSiteSeeds(recipe, dirname(recipePath))
@@ -3828,9 +3846,10 @@ function recipeDryRunExtraPlugins(recipe: WorkspaceRecipe, recipeDirectory: stri
       sourceRef: plugin.source,
       sourceType: source.type,
       slug,
-      target: `/wordpress/wp-content/plugins/${slug}`,
+      target: pluginTarget(slug, plugin.loadAs ?? "plugin"),
       pluginFile: recipeExtraPluginFile(plugin),
       activate: plugin.activate !== false,
+      loadAs: plugin.loadAs ?? "plugin",
       provenance,
     }
   })
@@ -4433,13 +4452,15 @@ async function prepareRecipeExtraPlugins(recipe: WorkspaceRecipe, recipeDirector
     const slug = recipeExtraPluginSlug(plugin)
     const resolved = await prepareRecipeSource(plugin.source, recipeDirectory, slug, plugin.sha256)
     const pluginFile = await resolveRecipeExtraPluginFile(plugin, recipeDirectory)
+    const loadAs = plugin.loadAs ?? "plugin"
     await assertPreparedPluginFileExists(resolved.source, pluginFile.slice(slug.length + 1), plugin.source)
     plugins.push({
       source: resolved.source,
       slug,
-      target: `/wordpress/wp-content/plugins/${slug}`,
+      target: pluginTarget(slug, loadAs),
       pluginFile,
       activate: plugin.activate !== false,
+      loadAs,
       cleanupPaths: resolved.cleanupPaths,
       provenance: resolved.provenance,
     })
@@ -4854,6 +4875,14 @@ function recipeExtraPluginFile(plugin: WorkspaceRecipeExtraPlugin): string {
   return plugin.pluginFile ?? `${slug}/${slug}.php`
 }
 
+function pluginTarget(slug: string, loadAs: PreparedExtraPlugin["loadAs"]): string {
+  if (loadAs === "mu-plugin") {
+    return `/wordpress/wp-content/mu-plugins/wp-codebox-runtime/${slug}`
+  }
+
+  return `/wordpress/wp-content/plugins/${slug}`
+}
+
 async function resolveRecipeExtraPluginFile(plugin: WorkspaceRecipeExtraPlugin, recipeDirectory: string): Promise<string> {
   const slug = recipeExtraPluginSlug(plugin)
   if (plugin.pluginFile) {
@@ -4880,7 +4909,7 @@ async function resolveRecipeExtraPluginFile(plugin: WorkspaceRecipeExtraPlugin,
 
 function activateExtraPluginsCode(extraPlugins: PreparedExtraPlugin[]): string | null {
   const pluginFiles = extraPlugins
-    .filter((plugin) => plugin.activate !== false)
+    .filter((plugin) => plugin.loadAs === "plugin" && plugin.activate !== false)
     .map((plugin) => plugin.pluginFile)
 
   if (pluginFiles.length === 0) {
@@ -4906,6 +4935,55 @@ foreach ($plugins as $plugin) {
 echo wp_json_encode(array('command' => 'activate-extra-plugins', 'plugins' => $activated), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);`
 }
 
+function installMuPluginsCode(extraPlugins: PreparedExtraPlugin[]): string | null {
+  const muPlugins = extraPlugins
+    .filter((plugin) => plugin.loadAs === "mu-plugin")
+    .map((plugin) => plugin.pluginFile)
+
+  if (muPlugins.length === 0) {
+    return null
+  }
+
+  return `$plugins = ${JSON.stringify(muPlugins)};
+$runtime_dir = WPMU_PLUGIN_DIR . '/wp-codebox-runtime';
+if (!is_dir(WPMU_PLUGIN_DIR) && !mkdir(WPMU_PLUGIN_DIR, 0777, true) && !is_dir(WPMU_PLUGIN_DIR)) {
+    throw new RuntimeException('Could not create mu-plugins directory.');
+}
+if (!is_dir($runtime_dir)) {
+    throw new RuntimeException('WP Codebox runtime mu-plugin directory is not mounted.');
+}
+$loader = WPMU_PLUGIN_DIR . '/wp-codebox-runtime-loader.php';
+$lines = array(
+    '<?php',
+    '/**',
+    ' * Plugin Name: WP Codebox Runtime Loader',
+    ' * Description: Loads WP Codebox runtime substrate as must-use plugins.',
+    ' */',
+    '',
+    "defined( 'ABSPATH' ) || exit;",
+    '',
+    "if ( ! defined( 'DATAMACHINE_WORKSPACE_PATH' ) ) {",
+    "    define( 'DATAMACHINE_WORKSPACE_PATH', ${JSON.stringify(SANDBOX_WORKSPACE_ROOT)} );",
+    "}",
+    "add_filter( 'datamachine_should_load_full_runtime', '__return_true', 1 );",
+    '',
+);
+foreach ($plugins as $plugin) {
+    if ('' === $plugin || str_starts_with($plugin, '/') || str_contains($plugin, '..') || !str_ends_with($plugin, '.php')) {
+        throw new RuntimeException('Unsafe WP Codebox runtime mu-plugin entry.');
+    }
+    $plugin_file = $runtime_dir . '/' . $plugin;
+    if (!file_exists($plugin_file)) {
+        throw new RuntimeException(sprintf('WP Codebox runtime mu-plugin is not mounted: %s', $plugin));
+    }
+    $lines[] = "require_once WPMU_PLUGIN_DIR . '/wp-codebox-runtime/" . str_replace("'", "\\'", $plugin) . "';";
+}
+if (false === file_put_contents($loader, implode("\\n", $lines) . "\\n")) {
+    throw new RuntimeException('Could not write WP Codebox runtime mu-plugin loader.');
+}
+echo wp_json_encode(array('command' => 'install-mu-plugins', 'plugins' => $plugins, 'loader' => $loader), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);`
+}
+
 function parseMount(value: string): RunOptions["mounts"][number] {
   const [source, target, mode = "readwrite"] = value.split(":")
 

packages/runtime-core/src/index.ts

@@ -494,6 +494,7 @@ export interface WorkspaceRecipeExtraPlugin {
   pluginFile?: string
   activate?: boolean
   sha256?: string
+  loadAs?: "plugin" | "mu-plugin"
 }
 
 export type WorkspaceRecipeSiteSeedType = "fixture" | "parent_site"

packages/wordpress-plugin/src/class-wp-codebox-agent-sandbox-runner.php

@@ -1806,6 +1806,7 @@ private function component_plugins( array $paths ): array {
 				'source'   => $paths[ $key ],
 				'slug'     => $slug,
 				'activate' => false,
+				'loadAs'   => 'mu-plugin',
 			);
 		}
 

scripts/recipe-dry-run-smoke.ts

@@ -45,6 +45,13 @@ writeFileSync(recipePath, `${JSON.stringify({
         slug: "simple-plugin",
         pluginFile: "simple-plugin/simple-plugin.php",
       },
+      {
+        source: "../../examples/simple-plugin",
+        slug: "simple-runtime",
+        pluginFile: "simple-runtime/simple-plugin.php",
+        activate: false,
+        loadAs: "mu-plugin",
+      },
     ],
     siteSeeds: [
       {
@@ -203,6 +210,9 @@ assert.equal(output.plan.workspaces[0].sourceMode, "site-backed")
 assert.equal(output.plan.workspaces[0].metadata.workspaceRoot, "/workspace")
 assert.equal(output.plan.workspaces[0].metadata.sourceMode, "site-backed")
 assert.equal(output.plan.extra_plugins[0].target, "/wordpress/wp-content/plugins/simple-plugin")
+assert.equal(output.plan.extra_plugins[0].loadAs, "plugin")
+assert.equal(output.plan.extra_plugins[1].target, "/wordpress/wp-content/mu-plugins/wp-codebox-runtime/simple-runtime")
+assert.equal(output.plan.extra_plugins[1].loadAs, "mu-plugin")
 assert.equal(output.plan.siteSeeds.length, 2)
 assert.equal(output.plan.siteSeeds[0].source, fixtureSeedPath)
 assert.equal(output.plan.siteSeeds[0].dryRunOnly, false)
@@ -216,13 +226,15 @@ assert.equal(output.plan.siteSeeds[1].privacy.importsIntoSandbox, false)
 assert.equal(output.plan.secretEnv[0].name, "DRY_RUN_TOKEN")
 assert.equal(Object.prototype.hasOwnProperty.call(output.plan.secretEnv[0], "value"), false)
 assert.equal(output.plan.secretEnv[0].available, true)
-assert.equal(output.plan.workflow.steps.length, 3)
-assert.equal(output.plan.workflow.steps[0].command, "activate-extra-plugins")
+assert.equal(output.plan.workflow.steps.length, 4)
+assert.equal(output.plan.workflow.steps[0].command, "install-mu-plugins")
 assert.equal(output.plan.workflow.steps[0].policy.status, "allowed")
-assert.equal(output.plan.workflow.steps[1].resolvedCommand, "wordpress.run-php")
-assert.equal(output.plan.workflow.steps[1].resolvedParsedArgs.code, "echo 'dry run';")
-assert.equal(output.plan.workflow.steps[2].parsedArgs.command, "option get home")
-assert.equal(output.plan.workflow.steps[2].policy.status, "allowed")
+assert.equal(output.plan.workflow.steps[1].command, "activate-extra-plugins")
+assert.equal(output.plan.workflow.steps[1].policy.status, "allowed")
+assert.equal(output.plan.workflow.steps[2].resolvedCommand, "wordpress.run-php")
+assert.equal(output.plan.workflow.steps[2].resolvedParsedArgs.code, "echo 'dry run';")
+assert.equal(output.plan.workflow.steps[3].parsedArgs.command, "option get home")
+assert.equal(output.plan.workflow.steps[3].policy.status, "allowed")
 assert.equal(output.runtime, undefined)
 assert.equal(output.executions, undefined)
 assert.equal(output.artifacts, undefined)

tests/smoke-wordpress-plugin.php

@@ -750,6 +750,7 @@ function get_users( array $args ): array { return array( new WP_User( 11, 'Priva
 $assert( 'runner recipe passes default provider', str_contains( $captured_recipe, 'openai' ) );
 $assert( 'runner recipe passes default model', str_contains( $captured_recipe, 'gpt-5.5' ) );
 $assert( 'runner recipe passes provider plugin path', str_contains( $captured_recipe, 'ai-provider-test' ) );
+$assert( 'runner recipe loads runtime components as mu-plugins', str_contains( $captured_recipe, '"slug":"agents-api","activate":false,"loadAs":"mu-plugin"' ) && str_contains( $captured_recipe, '"slug":"data-machine","activate":false,"loadAs":"mu-plugin"' ) && str_contains( $captured_recipe, '"slug":"data-machine-code","activate":false,"loadAs":"mu-plugin"' ) );
 $assert( 'runner recipe passes generic mount metadata', str_contains( $captured_recipe, 'example/editable-plugin' ) && str_contains( $captured_recipe, 'repo_root_relative_to_mount' ) );
 $assert( 'runner recipe passes secret env name only', str_contains( $captured_recipe, 'GITHUB_TOKEN' ) && ! str_contains( $captured_recipe, 'GITHUB_TOKEN=' ) );
 $assert( 'runner does not pass raw code options', ! str_contains( $captured_command, '--code ' ) && ! str_contains( $captured_command, '--code-file' ) );