@objectstack/runtime 7.7.0 → 7.9.0

package/dist/index.d.cts

@@ -1959,6 +1959,26 @@ declare class FileArtifactApiClient {
     private defaultLocalSqliteRuntime;
 }
 
+/**
+ * createObjectOSStack
+ *
+ * ObjectOS pure-runtime stack — no control-plane database, no auth /
+ * security / audit / tenant plugins. The host kernel registers:
+ *
+ *   - A minimal engine triplet (ObjectQL + in-memory DriverPlugin +
+ *     MetadataPlugin) so CLI auto-injected plugins (Setup, Studio,
+ *     Dispatcher, REST) and the runtime can boot. The host kernel itself
+ *     never reads or writes business data — every record query is routed
+ *     to a per-project kernel built from a remote artifact.
+ *   - The `env-registry` and `kernel-manager` services, so the runtime's
+ *     HTTP dispatcher can resolve hostnames and dispatch every request
+ *     to the matching project kernel.
+ *
+ * Invoked by `createRuntimeStack()` whenever `OS_CLOUD_URL`
+ * (or `config.controlPlaneUrl`) is set. The same plugin shape is returned
+ * as `createCloudStack()` so host configs can swap stacks transparently.
+ */
+
 interface ObjectOSStackConfig {
     /**
      * Control-plane base URL (HTTP) or a sentinel of `'file'` for the
@@ -1992,6 +2012,30 @@ interface ObjectOSStackConfig {
     artifactCacheTtlMs?: number;
     /** API prefix (carried for parity with cloud-stack). Default: /api/v1. */
     apiPrefix?: string;
+    /**
+     * Host-supplied runtime plugins appended to the stack's default plugin
+     * list. This is the official seam for a host (e.g. the ObjectStack Cloud
+     * repo) to add **product/policy** plugins — marketplace install, cloud-
+     * account binding, set-initial-password — to the otherwise-neutral
+     * framework runtime, WITHOUT a framework release and without reaching into
+     * the returned array by hand.
+     *
+     * They are appended last, so they mount their routes after the framework
+     * plugins and can override/augment behaviour (e.g. supply a credentialled
+     * install path that the browse-only MarketplaceProxyPlugin deliberately
+     * does not). See docs/design/cloud-account-binding-marketplace-install.md
+     * (ADR §5.2 — "framework exposes seams; cloud supplies metadata + policy").
+     */
+    extraPlugins?: Plugin[];
+    /**
+     * Capability tokens force-mounted on EVERY per-environment kernel, in
+     * addition to whatever the app artifact declares in `requires`. Merged and
+     * de-duped with `bundle.requires` before the capability loader runs. This
+     * is the host seam for a cloud operator to make a capability ubiquitous
+     * across all tenants without editing each app — e.g. `['ai','aiStudio']`
+     * so every cloud environment supports AI-driven online development.
+     */
+    defaultRequires?: string[];
 }
 interface ObjectOSStackResult {
     plugins: any[];
@@ -2213,6 +2257,14 @@ interface RuntimeConfigPluginConfig {
     controlPlaneUrl?: string;
     /** Override the `features.installLocal` flag. Default: false. */
     installLocal?: boolean;
+    /**
+     * Override the `features.aiStudio` flag — whether the SPA should surface
+     * AI-driven metadata authoring ("online development") affordances. Default:
+     * true (the actual authoring capability is still gated server-side by the
+     * presence of the `metadata_assistant` agent / @objectstack/service-ai-studio
+     * package; set false to force-hide the authoring UI for a tier/deployment).
+     */
+    aiStudio?: boolean;
     /**
      * Report this runtime as a single-environment deployment (CLI
      * `objectstack dev` / `os serve`). Defaults to `false` for
@@ -2234,6 +2286,7 @@ declare class RuntimeConfigPlugin implements Plugin {
     readonly version = "1.0.0";
     private readonly cloudUrl;
     private readonly installLocal;
+    private readonly aiStudio;
     private readonly singleEnvironment;
     private readonly productName;
     private readonly productShortName;
@@ -2365,6 +2418,12 @@ interface ArtifactKernelFactoryConfig {
      * `process.env.OS_AUTH_SECRET` / `AUTH_SECRET` at construction time.
      */
     authBaseSecret?: string;
+    /**
+     * Capability tokens force-mounted on every per-environment kernel, merged
+     * (and de-duped by the loader) with the artifact's own `requires`. Lets a
+     * host make a capability ubiquitous across tenants — e.g. `['ai','aiStudio']`.
+     */
+    defaultRequires?: string[];
 }
 declare class ArtifactKernelFactory implements EnvironmentKernelFactory {
     private readonly client;
@@ -2372,6 +2431,7 @@ declare class ArtifactKernelFactory implements EnvironmentKernelFactory {
     private readonly logger;
     private readonly kernelConfig?;
     private readonly authBaseSecret;
+    private readonly defaultRequires;
     constructor(config: ArtifactKernelFactoryConfig);
     create(environmentId: string): Promise<ObjectKernel>;
 }

package/dist/index.d.ts

@@ -1959,6 +1959,26 @@ declare class FileArtifactApiClient {
     private defaultLocalSqliteRuntime;
 }
 
+/**
+ * createObjectOSStack
+ *
+ * ObjectOS pure-runtime stack — no control-plane database, no auth /
+ * security / audit / tenant plugins. The host kernel registers:
+ *
+ *   - A minimal engine triplet (ObjectQL + in-memory DriverPlugin +
+ *     MetadataPlugin) so CLI auto-injected plugins (Setup, Studio,
+ *     Dispatcher, REST) and the runtime can boot. The host kernel itself
+ *     never reads or writes business data — every record query is routed
+ *     to a per-project kernel built from a remote artifact.
+ *   - The `env-registry` and `kernel-manager` services, so the runtime's
+ *     HTTP dispatcher can resolve hostnames and dispatch every request
+ *     to the matching project kernel.
+ *
+ * Invoked by `createRuntimeStack()` whenever `OS_CLOUD_URL`
+ * (or `config.controlPlaneUrl`) is set. The same plugin shape is returned
+ * as `createCloudStack()` so host configs can swap stacks transparently.
+ */
+
 interface ObjectOSStackConfig {
     /**
      * Control-plane base URL (HTTP) or a sentinel of `'file'` for the
@@ -1992,6 +2012,30 @@ interface ObjectOSStackConfig {
     artifactCacheTtlMs?: number;
     /** API prefix (carried for parity with cloud-stack). Default: /api/v1. */
     apiPrefix?: string;
+    /**
+     * Host-supplied runtime plugins appended to the stack's default plugin
+     * list. This is the official seam for a host (e.g. the ObjectStack Cloud
+     * repo) to add **product/policy** plugins — marketplace install, cloud-
+     * account binding, set-initial-password — to the otherwise-neutral
+     * framework runtime, WITHOUT a framework release and without reaching into
+     * the returned array by hand.
+     *
+     * They are appended last, so they mount their routes after the framework
+     * plugins and can override/augment behaviour (e.g. supply a credentialled
+     * install path that the browse-only MarketplaceProxyPlugin deliberately
+     * does not). See docs/design/cloud-account-binding-marketplace-install.md
+     * (ADR §5.2 — "framework exposes seams; cloud supplies metadata + policy").
+     */
+    extraPlugins?: Plugin[];
+    /**
+     * Capability tokens force-mounted on EVERY per-environment kernel, in
+     * addition to whatever the app artifact declares in `requires`. Merged and
+     * de-duped with `bundle.requires` before the capability loader runs. This
+     * is the host seam for a cloud operator to make a capability ubiquitous
+     * across all tenants without editing each app — e.g. `['ai','aiStudio']`
+     * so every cloud environment supports AI-driven online development.
+     */
+    defaultRequires?: string[];
 }
 interface ObjectOSStackResult {
     plugins: any[];
@@ -2213,6 +2257,14 @@ interface RuntimeConfigPluginConfig {
     controlPlaneUrl?: string;
     /** Override the `features.installLocal` flag. Default: false. */
     installLocal?: boolean;
+    /**
+     * Override the `features.aiStudio` flag — whether the SPA should surface
+     * AI-driven metadata authoring ("online development") affordances. Default:
+     * true (the actual authoring capability is still gated server-side by the
+     * presence of the `metadata_assistant` agent / @objectstack/service-ai-studio
+     * package; set false to force-hide the authoring UI for a tier/deployment).
+     */
+    aiStudio?: boolean;
     /**
      * Report this runtime as a single-environment deployment (CLI
      * `objectstack dev` / `os serve`). Defaults to `false` for
@@ -2234,6 +2286,7 @@ declare class RuntimeConfigPlugin implements Plugin {
     readonly version = "1.0.0";
     private readonly cloudUrl;
     private readonly installLocal;
+    private readonly aiStudio;
     private readonly singleEnvironment;
     private readonly productName;
     private readonly productShortName;
@@ -2365,6 +2418,12 @@ interface ArtifactKernelFactoryConfig {
      * `process.env.OS_AUTH_SECRET` / `AUTH_SECRET` at construction time.
      */
     authBaseSecret?: string;
+    /**
+     * Capability tokens force-mounted on every per-environment kernel, merged
+     * (and de-duped by the loader) with the artifact's own `requires`. Lets a
+     * host make a capability ubiquitous across tenants — e.g. `['ai','aiStudio']`.
+     */
+    defaultRequires?: string[];
 }
 declare class ArtifactKernelFactory implements EnvironmentKernelFactory {
     private readonly client;
@@ -2372,6 +2431,7 @@ declare class ArtifactKernelFactory implements EnvironmentKernelFactory {
     private readonly logger;
     private readonly kernelConfig?;
     private readonly authBaseSecret;
+    private readonly defaultRequires;
     constructor(config: ArtifactKernelFactoryConfig);
     create(environmentId: string): Promise<ObjectKernel>;
 }

package/dist/index.js

@@ -300,6 +300,24 @@ var init_seed_loader = __esm({
           for (const ref of objectRefs) {
             const fieldValue = record[ref.field];
             if (fieldValue === void 0 || fieldValue === null) continue;
+            if (typeof fieldValue === "object") {
+              const wrapped = fieldValue.externalId;
+              const hint = wrapped !== void 0 ? ` Pass the natural key directly: ${ref.field}: ${JSON.stringify(wrapped)}.` : ` Pass the target's ${ref.targetField} value as a plain string.`;
+              const error = {
+                sourceObject: objectName,
+                field: ref.field,
+                targetObject: ref.targetObject,
+                targetField: ref.targetField,
+                attemptedValue: fieldValue,
+                recordIndex: i,
+                message: `Invalid reference for ${objectName}.${ref.field}: expected a ${ref.targetObject}.${ref.targetField} natural-key string but got an object.${hint}`
+              };
+              errors.push(error);
+              allErrors.push(error);
+              this.logger.warn(`[SeedLoader] ${error.message}`, { recordIndex: i });
+              record[ref.field] = null;
+              continue;
+            }
             if (typeof fieldValue !== "string" || this.looksLikeInternalId(fieldValue)) continue;
             const targetMap = insertedRecords.get(ref.targetObject);
             const resolvedId = targetMap?.get(String(fieldValue));
@@ -3496,7 +3514,8 @@ var _HttpDispatcher = class _HttpDispatcher {
         if (protocol && typeof protocol.getMetaItem === "function") {
           try {
             const organizationId = await this.resolveActiveOrganizationId(_context);
-            const data = await protocol.getMetaItem({ type: singularType, name, packageId, organizationId });
+            const previewDrafts = query?.preview === "draft";
+            const data = await protocol.getMetaItem({ type: singularType, name, packageId, organizationId, previewDrafts });
             return { handled: true, response: this.success(data) };
           } catch (e) {
           }
@@ -3514,6 +3533,23 @@ var _HttpDispatcher = class _HttpDispatcher {
         return { handled: true, response: this.error(e.message, 404) };
       }
     }
+    if (parts.length === 1 && parts[0] === "_drafts" && (!method || method.toUpperCase() === "GET")) {
+      const protocol = await this.resolveService("protocol");
+      if (protocol && typeof protocol.listDrafts === "function") {
+        try {
+          const organizationId = await this.resolveActiveOrganizationId(_context);
+          const data = await protocol.listDrafts({
+            packageId: query?.packageId || void 0,
+            type: query?.type || void 0,
+            organizationId
+          });
+          return { handled: true, response: this.success(data) };
+        } catch (e) {
+          return { handled: true, response: this.error(e.message, 500) };
+        }
+      }
+      return { handled: true, response: this.error("Draft listing not supported", 501) };
+    }
     if (parts.length === 1) {
       const typeOrName = parts[0];
       const packageId = query?.package || void 0;
@@ -3521,7 +3557,8 @@ var _HttpDispatcher = class _HttpDispatcher {
       if (protocol && typeof protocol.getMetaItems === "function") {
         try {
           const organizationId = await this.resolveActiveOrganizationId(_context);
-          const data = await protocol.getMetaItems({ type: typeOrName, packageId, organizationId });
+          const previewDrafts = query?.preview === "draft";
+          const data = await protocol.getMetaItems({ type: typeOrName, packageId, organizationId, previewDrafts });
           if (data && (data.items !== void 0 || Array.isArray(data))) {
             return { handled: true, response: this.success(data) };
           }
@@ -3813,7 +3850,15 @@ var _HttpDispatcher = class _HttpDispatcher {
         return { handled: true, response: this.success({ packages, total: packages.length }) };
       }
       if (parts.length === 0 && m === "POST") {
-        const pkg = registry.installPackage(body.manifest || body, body.settings);
+        const manifest = body.manifest || body;
+        let pkg;
+        const protocolSvc = await this.resolveService("protocol").catch(() => null);
+        if (protocolSvc && typeof protocolSvc.installPackage === "function") {
+          const out = await protocolSvc.installPackage({ manifest, settings: body.settings });
+          pkg = out?.package ?? out;
+        } else {
+          pkg = registry.installPackage(manifest, body.settings);
+        }
         const res = this.success(pkg);
         res.status = 201;
         return { handled: true, response: res };
@@ -3849,6 +3894,42 @@ var _HttpDispatcher = class _HttpDispatcher {
         }
         return { handled: true, response: this.error("Metadata service not available", 503) };
       }
+      if (parts.length === 2 && parts[1] === "publish-drafts" && m === "POST") {
+        const id = decodeURIComponent(parts[0]);
+        const protocol = await this.resolveService("protocol");
+        if (protocol && typeof protocol.publishPackageDrafts === "function") {
+          try {
+            const organizationId = await this.resolveActiveOrganizationId(_context);
+            const result = await protocol.publishPackageDrafts({
+              packageId: id,
+              ...organizationId ? { organizationId } : {},
+              ...body?.actor ? { actor: body.actor } : {}
+            });
+            return { handled: true, response: this.success(result) };
+          } catch (e) {
+            return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+          }
+        }
+        return { handled: true, response: this.error("Draft publishing not supported", 501) };
+      }
+      if (parts.length === 2 && parts[1] === "discard-drafts" && m === "POST") {
+        const id = decodeURIComponent(parts[0]);
+        const protocol = await this.resolveService("protocol");
+        if (protocol && typeof protocol.discardPackageDrafts === "function") {
+          try {
+            const organizationId = await this.resolveActiveOrganizationId(_context);
+            const result = await protocol.discardPackageDrafts({
+              packageId: id,
+              ...organizationId ? { organizationId } : {},
+              ...body?.actor ? { actor: body.actor } : {}
+            });
+            return { handled: true, response: this.success(result) };
+          } catch (e) {
+            return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+          }
+        }
+        return { handled: true, response: this.error("Draft discarding not supported", 501) };
+      }
       if (parts.length === 2 && parts[1] === "revert" && m === "POST") {
         const id = decodeURIComponent(parts[0]);
         const metadataService = await this.getService(CoreServiceName.enum.metadata);
@@ -3874,9 +3955,27 @@ var _HttpDispatcher = class _HttpDispatcher {
       }
       if (parts.length === 1 && m === "DELETE") {
         const id = decodeURIComponent(parts[0]);
-        const success = registry.uninstallPackage(id);
-        if (!success) return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
-        return { handled: true, response: this.success({ success: true }) };
+        const registryRemoved = registry.uninstallPackage(id);
+        let persisted = void 0;
+        const protocol = await this.resolveService("protocol");
+        if (protocol && typeof protocol.deletePackage === "function") {
+          try {
+            const organizationId = await this.resolveActiveOrganizationId(_context);
+            const keepData = query?.keepData === "true" || query?.keepData === "1";
+            persisted = await protocol.deletePackage({
+              packageId: id,
+              ...organizationId ? { organizationId } : {},
+              ...keepData ? { keepData: true } : {}
+            });
+          } catch (e) {
+            return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+          }
+        }
+        const deletedCount = persisted?.deletedCount ?? 0;
+        if (!registryRemoved && deletedCount === 0) {
+          return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
+        }
+        return { handled: true, response: this.success({ success: true, registryRemoved, persisted }) };
       }
     } catch (e) {
       return { handled: true, response: this.error(e.message, e.statusCode || 500) };
@@ -5358,6 +5457,14 @@ function createDispatcherPlugin(config = {}) {
           errorResponse(err, res);
         }
       });
+      server.post(`${prefix}/packages/:id/publish-drafts`, async (req, res) => {
+        try {
+          const result = await dispatcher.handlePackages(`/${req.params.id}/publish-drafts`, "POST", req.body, {}, { request: req });
+          sendResult(result, res);
+        } catch (err) {
+          errorResponse(err, res);
+        }
+      });
       server.post(`${prefix}/packages/:id/revert`, async (req, res) => {
         try {
           const result = await dispatcher.handlePackages(`/${req.params.id}/revert`, "POST", req.body, {}, { request: req });
@@ -6459,6 +6566,16 @@ var CAPABILITY_PROVIDERS = {
     pkg: "@objectstack/service-ai",
     export: "AIServicePlugin"
   },
+  // AI Studio — AI-driven metadata authoring ("online development"). This is
+  // a commercial capability that ships in the private @objectstack/service-ai-studio
+  // package (not part of the open-source framework). The dynamic import below
+  // silently skips when the package isn't installed, so the open-source build
+  // is unaffected; cloud and enterprise installs that ship the package light it
+  // up. Pair with `ai` in `requires` (it attaches via the `ai:ready` hook).
+  aiStudio: {
+    pkg: "@objectstack/service-ai-studio",
+    export: "AIStudioPlugin"
+  },
   analytics: {
     pkg: "@objectstack/service-analytics",
     export: "AnalyticsServicePlugin",
@@ -6785,6 +6902,7 @@ var ArtifactKernelFactory = class {
     this.envRegistry = config.envRegistry;
     this.logger = config.logger ?? console;
     this.kernelConfig = config.kernelConfig;
+    this.defaultRequires = config.defaultRequires ?? [];
     this.authBaseSecret = (config.authBaseSecret ?? readEnvWithDeprecation3("OS_AUTH_SECRET", ["AUTH_SECRET", "BETTER_AUTH_SECRET"]) ?? "").trim();
   }
   async create(environmentId) {
@@ -6951,7 +7069,10 @@ var ArtifactKernelFactory = class {
       });
     }
     const requiresRaw = (Array.isArray(bundle?.requires) ? bundle.requires : null) ?? (Array.isArray(sys?.requires) ? sys.requires : null) ?? [];
-    const requires = requiresRaw.filter((x) => typeof x === "string" && x.length > 0);
+    const requires = [
+      ...requiresRaw,
+      ...this.defaultRequires
+    ].filter((x) => typeof x === "string" && x.length > 0);
     if (requires.length > 0) {
       const installed = await loadCapabilities({
         kernel,
@@ -7370,6 +7491,61 @@ var AuthProxyPlugin = class {
                 return c.text(`sso-exchange failed: ${err?.message ?? String(err)}`, 500);
               }
             }
+            if (c.req.method === "POST" && subPath === "set-initial-password") {
+              try {
+                let body = {};
+                try {
+                  body = await c.req.json();
+                } catch {
+                  body = {};
+                }
+                const newPassword = body?.newPassword;
+                if (typeof newPassword !== "string" || newPassword.length === 0) {
+                  return c.json({ success: false, error: { code: "invalid_request", message: "newPassword is required" } }, 400);
+                }
+                if (typeof authSvc?.getAuthContext !== "function") {
+                  return c.json({ success: false, error: { code: "unavailable", message: "Auth context unavailable" } }, 503);
+                }
+                let userId;
+                try {
+                  const api = typeof authSvc.getApi === "function" ? await authSvc.getApi() : null;
+                  const session = await api?.getSession?.({ headers: c.req.raw.headers });
+                  userId = session?.user?.id ? String(session.user.id) : void 0;
+                } catch {
+                }
+                if (!userId) {
+                  return c.json({ success: false, error: { code: "unauthorized", message: "Sign in first" } }, 401);
+                }
+                const setPwCtx = await authSvc.getAuthContext();
+                if (!setPwCtx?.internalAdapter || !setPwCtx?.password) {
+                  return c.json({ success: false, error: { code: "unavailable", message: "Auth context unavailable" } }, 503);
+                }
+                const minLen = setPwCtx.password?.config?.minPasswordLength ?? 8;
+                const maxLen = setPwCtx.password?.config?.maxPasswordLength ?? 128;
+                if (newPassword.length < minLen) {
+                  return c.json({ success: false, error: { code: "password_too_short", message: `Password must be at least ${minLen} characters` } }, 400);
+                }
+                if (newPassword.length > maxLen) {
+                  return c.json({ success: false, error: { code: "password_too_long", message: `Password must be at most ${maxLen} characters` } }, 400);
+                }
+                const accounts = await setPwCtx.internalAdapter.findAccounts(userId);
+                const existingCredential = accounts?.find?.((a) => a.providerId === "credential" && a.password);
+                if (existingCredential) {
+                  return c.json({ success: false, error: { code: "credential_account_exists", message: "A local password is already set for this account. Use change-password instead." } }, 409);
+                }
+                const passwordHash = await setPwCtx.password.hash(newPassword);
+                await setPwCtx.internalAdapter.createAccount({
+                  userId,
+                  providerId: "credential",
+                  accountId: userId,
+                  password: passwordHash
+                });
+                return c.json({ success: true });
+              } catch (err) {
+                ctx.logger?.error?.("[AuthProxyPlugin] set-initial-password failed", err instanceof Error ? err : new Error(String(err)));
+                return c.json({ success: false, error: { code: "set_password_failed", message: String(err?.message ?? err) } }, 500);
+              }
+            }
             const fn = await resolveAuthHandler(authSvc);
             if (!fn) {
               return c.json({ error: "auth_service_unavailable", environmentId }, 503);
@@ -7555,13 +7731,7 @@ var MarketplaceProxyPlugin = class _MarketplaceProxyPlugin {
             }
             const target = `${cloudUrl}${incomingUrl.pathname}${incomingUrl.search}`;
             if (method !== "GET" && method !== "HEAD") {
-              return c.json({
-                success: false,
-                error: {
-                  code: "marketplace_method_not_allowed",
-                  message: `Marketplace proxy only forwards GET/HEAD; install via cloud.`
-                }
-              }, 405);
+              return next();
             }
             const accept = c.req.header("accept") ?? "application/json";
             const acceptLang = c.req.header("accept-language") ?? "";
@@ -7785,7 +7955,8 @@ var RuntimeConfigPlugin = class {
         const rawApp = httpServer.getRawApp();
         const features = {
           installLocal: this.installLocal,
-          marketplace: true
+          marketplace: true,
+          aiStudio: this.aiStudio
         };
         let envRegistry = null;
         try {
@@ -7836,6 +8007,7 @@ var RuntimeConfigPlugin = class {
     };
     this.cloudUrl = config.controlPlaneUrl === "" ? "" : resolveCloudUrl(config.controlPlaneUrl) ?? "";
     this.installLocal = !!config.installLocal;
+    this.aiStudio = config.aiStudio !== false;
     this.singleEnvironment = !!config.singleEnvironment;
     const envName = (typeof process !== "undefined" ? process.env?.OS_PRODUCT_NAME : void 0)?.trim();
     const envShort = (typeof process !== "undefined" ? process.env?.OS_PRODUCT_SHORT_NAME : void 0)?.trim();
@@ -8027,7 +8199,8 @@ var ObjectOSEnvironmentPlugin = class {
       const factory = new ArtifactKernelFactory({
         client,
         envRegistry,
-        logger: ctx.logger
+        logger: ctx.logger,
+        defaultRequires: this.config.defaultRequires
       });
       const kernelManager = new KernelManager({
         factory,
@@ -8084,7 +8257,17 @@ async function createObjectOSStack(config) {
   };
   const enginePlugins = await createHostEnginePlugins();
   return {
-    plugins: [...enginePlugins, new ObjectOSEnvironmentPlugin(merged), new AuthProxyPlugin(), new MarketplaceProxyPlugin({ controlPlaneUrl: merged.controlPlaneUrl === "file" ? void 0 : merged.controlPlaneUrl }), new RuntimeConfigPlugin({ controlPlaneUrl: merged.controlPlaneUrl === "file" ? void 0 : merged.controlPlaneUrl, installLocal: false })],
+    plugins: [
+      ...enginePlugins,
+      new ObjectOSEnvironmentPlugin(merged),
+      new AuthProxyPlugin(),
+      new MarketplaceProxyPlugin({ controlPlaneUrl: merged.controlPlaneUrl === "file" ? void 0 : merged.controlPlaneUrl }),
+      new RuntimeConfigPlugin({ controlPlaneUrl: merged.controlPlaneUrl === "file" ? void 0 : merged.controlPlaneUrl, installLocal: false }),
+      // Host-supplied product/policy plugins (the official seam — see
+      // ObjectOSStackConfig.extraPlugins). Appended last so they mount
+      // after the framework defaults.
+      ...config.extraPlugins ?? []
+    ],
     api: {
       enableProjectScoping: true,
       projectResolution: "auto",