feat(runtime): tier-driven capability loader for ObjectOS per-project kernels

hotlong · Copilot · hotlong · commit 2856f6b6c51c · 2026-05-18T10:17:11.000+08:00
Add capability-loader.ts mirroring the CLI's CAPABILITY_PROVIDERS table so
artifact bundles' `requires: [...]` array drives plugin installation on
per-project kernels built by ArtifactKernelFactory.

Previously only 7 plugins loaded per project on objectos (driver, objectql,
metadata, auth, security, i18n, app). Flows/AI/Analytics declared in the
artifact were silently dropped because the host had no AutomationServicePlugin,
AIServicePlugin or AnalyticsServicePlugin registered.

Tokens supported (matches `defineStack({ requires })`):
  automation (+ crud/logic/http/screen node packs), ai, analytics,
  audit, cache, storage, queue, job, realtime, feed

Tier-gated capabilities (auth, ui, i18n) remain wired explicitly because
they need bespoke configuration (per-project HKDF secret, UI dist paths).

Lazy &amp; silent on missing deps — a host that doesn't bundle service-queue
just logs a warning and continues. apps/objectos already declares
service-automation/ai/analytics/feed in its package.json so dynamic imports
resolve at runtime.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/packages/runtime/src/cloud/artifact-kernel-factory.ts b/packages/runtime/src/cloud/artifact-kernel-factory.ts
@@ -34,6 +34,7 @@ import { AppPlugin } from '../app-plugin.js';
 import type { ProjectKernelFactory } from './kernel-manager.js';
 import type { EnvironmentDriverRegistry } from './environment-registry.js';
 import type { ArtifactApiClient } from './artifact-api-client.js';
+import { loadCapabilities } from './capability-loader.js';
 
 type IDataDriver = Contracts.IDataDriver;
 
@@ -218,6 +219,33 @@ export class ArtifactKernelFactory implements ProjectKernelFactory {
             });
         }
 
+        // Tier-driven capability loading: install service plugins listed
+        // in the artifact's `requires` array (e.g. ['ai','automation',
+        // 'analytics']). Must be registered BEFORE AppPlugin so that
+        // AppPlugin's start phase can hand off flows/agents/cubes to
+        // services that are already initialised.
+        const requiresRaw =
+            (Array.isArray(bundle?.requires) ? bundle.requires : null) ??
+            (Array.isArray(sys?.requires) ? sys.requires : null) ??
+            [];
+        const requires: string[] = (requiresRaw as unknown[])
+            .filter((x): x is string => typeof x === 'string' && x.length > 0);
+
+        if (requires.length > 0) {
+            const installed = await loadCapabilities({
+                kernel,
+                requires,
+                bundle: { ...(bundle ?? {}), ...(sys ?? {}) } as Record<string, unknown>,
+                logger: this.logger,
+                projectId,
+            });
+            this.logger.info?.('[ArtifactKernelFactory] capabilities loaded', {
+                projectId,
+                requires,
+                installed,
+            });
+        }
+
         await kernel.use(new AppPlugin(bundle, {
             projectId,
             organizationId: project.organization_id ?? '',
diff --git a/packages/runtime/src/cloud/capability-loader.ts b/packages/runtime/src/cloud/capability-loader.ts
@@ -0,0 +1,189 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Capability loader — `bundle.requires` driven dispatch.
+ *
+ * Mirrors the CAPABILITY_PROVIDERS table in
+ * `@objectstack/cli/src/commands/serve.ts` so that per-project kernels
+ * built by {@link ArtifactKernelFactory} pick up the same service plugins
+ * a developer would get when running `objectstack serve` locally.
+ *
+ * Design goals:
+ *   - Single source of truth: artifact's `requires` array. No hardcoded
+ *     plugin list per host.
+ *   - Lazy: each provider is dynamically imported only when requested,
+ *     keeping cold-start small for artifacts that don't need that
+ *     capability.
+ *   - Silent on missing deps: a host that doesn't ship the optional
+ *     package (e.g. service-queue) just logs a warn and continues.
+ */
+
+import type { ObjectKernel } from '@objectstack/core';
+
+export interface CapabilitySpec {
+    /** npm package name to import. */
+    pkg: string;
+    /** Named export — class constructor for the main plugin. */
+    export: string;
+    /**
+     * Optional bundle key that, when present, is forwarded as constructor
+     * argument (e.g. analytics needs `analyticsCubes`).
+     */
+    configKey?: string;
+    /** Auxiliary plugins loaded alongside the main one. */
+    extras?: Array<{ pkg: string; export: string }>;
+}
+
+/**
+ * Registry of `requires` token → plugin provider.
+ *
+ * Keep keys in sync with the user-facing tokens accepted by
+ * `defineStack({ requires: [...] })` and the CLI's CAPABILITY_PROVIDERS.
+ *
+ * Tier-gated capabilities (`auth`, `ui`, `i18n`) are intentionally NOT
+ * listed here — they are wired explicitly by the kernel factory because
+ * they need bespoke configuration (per-project HKDF secret, UI dist
+ * paths, etc).
+ */
+export const CAPABILITY_PROVIDERS: Record<string, CapabilitySpec> = {
+    automation: {
+        pkg: '@objectstack/service-automation',
+        export: 'AutomationServicePlugin',
+        extras: [
+            { pkg: '@objectstack/service-automation', export: 'CrudNodesPlugin' },
+            { pkg: '@objectstack/service-automation', export: 'LogicNodesPlugin' },
+            { pkg: '@objectstack/service-automation', export: 'HttpConnectorPlugin' },
+            { pkg: '@objectstack/service-automation', export: 'ScreenNodesPlugin' },
+        ],
+    },
+    ai: {
+        pkg: '@objectstack/service-ai',
+        export: 'AIServicePlugin',
+    },
+    analytics: {
+        pkg: '@objectstack/service-analytics',
+        export: 'AnalyticsServicePlugin',
+        configKey: 'analyticsCubes',
+    },
+    audit: {
+        pkg: '@objectstack/plugin-audit',
+        export: 'AuditPlugin',
+    },
+    cache: {
+        pkg: '@objectstack/service-cache',
+        export: 'CacheServicePlugin',
+    },
+    storage: {
+        pkg: '@objectstack/service-storage',
+        export: 'StorageServicePlugin',
+    },
+    queue: {
+        pkg: '@objectstack/service-queue',
+        export: 'QueueServicePlugin',
+    },
+    job: {
+        pkg: '@objectstack/service-job',
+        export: 'JobServicePlugin',
+    },
+    realtime: {
+        pkg: '@objectstack/service-realtime',
+        export: 'RealtimeServicePlugin',
+    },
+    feed: {
+        pkg: '@objectstack/service-feed',
+        export: 'FeedServicePlugin',
+    },
+};
+
+type Logger = { info?: (...a: any[]) => void; warn?: (...a: any[]) => void; error?: (...a: any[]) => void };
+
+export interface LoadCapabilitiesOptions {
+    kernel: ObjectKernel;
+    /** Tokens from `bundle.requires` (e.g. `['ai','automation','analytics']`). */
+    requires: readonly string[];
+    /** Compiled artifact metadata. Used to pull `configKey`-driven args. */
+    bundle: Record<string, unknown>;
+    /** Optional logger. */
+    logger?: Logger;
+    /** projectId for log breadcrumbs. */
+    projectId: string;
+}
+
+/**
+ * Walk `requires` and install each known capability on the kernel.
+ *
+ * Returns the list of plugin exports actually installed for diagnostics.
+ */
+export async function loadCapabilities(opts: LoadCapabilitiesOptions): Promise<string[]> {
+    const { kernel, requires, bundle, projectId } = opts;
+    const logger: Logger = opts.logger ?? console;
+    const installed: string[] = [];
+
+    for (const cap of requires) {
+        const spec = CAPABILITY_PROVIDERS[cap];
+        if (!spec) {
+            // Tier-gated capability (auth/ui/i18n) — wired elsewhere.
+            continue;
+        }
+
+        try {
+            const mod: any = await import(/* webpackIgnore: true */ spec.pkg);
+            const Ctor = mod[spec.export];
+            if (!Ctor) {
+                logger.warn?.(
+                    `[CapabilityLoader] '${cap}': package '${spec.pkg}' did not export '${spec.export}'`,
+                    { projectId },
+                );
+                continue;
+            }
+
+            let arg: unknown;
+            if (spec.configKey) {
+                const v = (bundle as Record<string, unknown>)[spec.configKey];
+                if (spec.configKey === 'analyticsCubes') {
+                    arg = { cubes: Array.isArray(v) ? v : [] };
+                } else if (v !== undefined) {
+                    arg = v;
+                }
+            }
+
+            await kernel.use(arg !== undefined ? new Ctor(arg) : new Ctor());
+            installed.push(spec.export);
+
+            if (spec.extras) {
+                for (const ex of spec.extras) {
+                    try {
+                        const exMod: any = await import(/* webpackIgnore: true */ ex.pkg);
+                        const ExCtor = exMod[ex.export];
+                        if (ExCtor) {
+                            await kernel.use(new ExCtor());
+                            installed.push(ex.export);
+                        }
+                    } catch {
+                        // Optional extra — silently skip.
+                    }
+                }
+            }
+
+            logger.info?.(
+                `[CapabilityLoader] '${cap}' installed (${spec.export}${spec.extras ? ' + ' + spec.extras.length + ' extras' : ''})`,
+                { projectId },
+            );
+        } catch (err: any) {
+            const msg = err?.message ?? String(err);
+            if (msg.includes('Cannot find module') || msg.includes('ERR_MODULE_NOT_FOUND')) {
+                logger.warn?.(
+                    `[CapabilityLoader] '${cap}' requested but '${spec.pkg}' not installed in host — skipped`,
+                    { projectId },
+                );
+            } else {
+                logger.error?.(
+                    `[CapabilityLoader] '${cap}' load failed: ${msg}`,
+                    { projectId },
+                );
+            }
+        }
+    }
+
+    return installed;
+}
