@objectstack/runtime 5.0.0 → 5.2.0

package/dist/index.d.cts

@@ -1,13 +1,14 @@
 import { ObjectKernel, IHttpServer, ObjectKernelConfig, Plugin, PluginContext, RouteHandler, Middleware } from '@objectstack/core';
 export * from '@objectstack/core';
 export { ObjectKernel } from '@objectstack/core';
+import { ClusterServicePluginOptions } from '@objectstack/service-cluster';
+import { ClusterCapabilityConfigInput, ExecutionContext } from '@objectstack/spec/kernel';
 import { z } from 'zod';
 import * as Contracts from '@objectstack/spec/contracts';
 import { ISeedLoaderService, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
 import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Dataset, SeedLoaderConfigInput, ExpressionBody, ScriptBody, HookBody, Hook } from '@objectstack/spec/data';
 import { MetricsRegistry, ErrorReporter } from '@objectstack/observability';
-export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, RUNTIME_METRICS } from '@objectstack/observability';
-import { ExecutionContext } from '@objectstack/spec/kernel';
+export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, OBSERVABILITY_ERRORS_SERVICE, OBSERVABILITY_METRICS_SERVICE, RUNTIME_METRICS } from '@objectstack/observability';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
 import { ProjectArtifact } from '@objectstack/spec/cloud';
 export { RestApiPluginConfig, RestServer, RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin } from '@objectstack/rest';
@@ -23,6 +24,18 @@ interface RuntimeConfig {
      * Kernel Configuration
      */
     kernel?: ObjectKernelConfig;
+    /**
+     * Cluster service configuration.
+     *
+     * - Omit (default): a single-node `memory` cluster is auto-registered.
+     * - `false`: skip auto-registration entirely. Register your own
+     *   `ClusterServicePlugin` if you need it later.
+     * - `ClusterCapabilityConfigInput`: forwarded to `defineCluster()`.
+     * - `{ cluster: IClusterService }`: bring your own instance.
+     *
+     * See `content/docs/concepts/cluster-semantics.mdx` for driver options.
+     */
+    cluster?: false | ClusterCapabilityConfigInput | ClusterServicePluginOptions;
 }
 /**
  * ObjectStack Runtime
@@ -41,6 +54,7 @@ interface RuntimeConfig {
 declare class Runtime {
     readonly kernel: ObjectKernel;
     constructor(config?: RuntimeConfig);
+    private normalizeClusterOptions;
     /**
      * Register a plugin
      */
@@ -61,10 +75,10 @@ declare const StandaloneStackConfigSchema: z.ZodObject<{
     databaseUrl: z.ZodOptional<z.ZodString>;
     databaseAuthToken: z.ZodOptional<z.ZodString>;
     databaseDriver: z.ZodOptional<z.ZodEnum<{
-        sqlite: "sqlite";
-        turso: "turso";
         memory: "memory";
         postgres: "postgres";
+        sqlite: "sqlite";
+        turso: "turso";
         mongodb: "mongodb";
     }>>;
     projectId: z.ZodOptional<z.ZodString>;
@@ -492,6 +506,75 @@ declare function parseTraceparent(value: unknown): TraceContext | undefined;
  */
 declare function formatTraceparent(ctx: TraceContext): string;
 
+/**
+ * Options for {@link ObservabilityServicePlugin}.
+ *
+ * Either or both backends can be omitted; the omitted one resolves to
+ * the corresponding no-op exporter so consumers can always rely on the
+ * service being present.
+ */
+interface ObservabilityServicePluginOptions {
+    /** Metrics backend (e.g. `ConsoleMetricsRegistry`, `OtlpHttpMetricsRegistry`). */
+    metrics?: MetricsRegistry;
+    /** Error reporter backend (e.g. Sentry adapter). */
+    errors?: ErrorReporter;
+}
+/**
+ * `ObservabilityServicePlugin` — registers the host's
+ * {@link MetricsRegistry} and {@link ErrorReporter} in the kernel
+ * service registry under the canonical names so any other plugin can
+ * look them up without each host having to thread observability config
+ * through every plugin constructor.
+ *
+ * Resolution chain other plugins should follow:
+ *
+ *   1. Explicit option on the plugin's own options object (escape
+ *      hatch for tests / explicit wiring).
+ *   2. `ctx.getService(OBSERVABILITY_METRICS_SERVICE)`.
+ *   3. `NoopMetricsRegistry()` — never null.
+ *
+ * Register this plugin **before** any plugin that wants to consume the
+ * services (cache, storage, dispatcher), otherwise the consumer's
+ * `init` will fall through to the no-op default.
+ *
+ * @example
+ * ```ts
+ * import { ObjectKernel } from '@objectstack/core';
+ * import {
+ *   ObservabilityServicePlugin,
+ *   CacheServicePlugin,
+ * } from '@objectstack/runtime';
+ * import { ConsoleMetricsRegistry } from '@objectstack/observability';
+ *
+ * const kernel = new ObjectKernel();
+ * kernel.use(new ObservabilityServicePlugin({
+ *   metrics: new ConsoleMetricsRegistry(),
+ * }));
+ * kernel.use(new CacheServicePlugin()); // picks metrics up automatically
+ * ```
+ */
+declare class ObservabilityServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: string;
+    private readonly options;
+    constructor(options?: ObservabilityServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+}
+/**
+ * Helper used by consumer plugins to resolve a metrics backend with
+ * the canonical fallback chain. Never throws; always returns a usable
+ * `MetricsRegistry`.
+ *
+ * @param ctx        the consuming plugin's `PluginContext`
+ * @param override   explicit option set on the consuming plugin (wins)
+ */
+declare function resolveMetrics(ctx: PluginContext, override?: MetricsRegistry): MetricsRegistry;
+/**
+ * Sibling of {@link resolveMetrics} for {@link ErrorReporter}.
+ */
+declare function resolveErrorReporter(ctx: PluginContext, override?: ErrorReporter): ErrorReporter;
+
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -1745,6 +1828,155 @@ interface ObjectOSStackResult {
 }
 declare function createObjectOSStack(config: ObjectOSStackConfig): Promise<ObjectOSStackResult>;
 
+/**
+ * MarketplaceProxyPlugin
+ *
+ * Forwards `GET /api/v1/marketplace/*` from a tenant ObjectOS runtime to
+ * the configured ObjectStack Cloud control-plane URL. The cloud endpoint
+ * (`packages/service-cloud/src/routes/marketplace.ts`) is unauthenticated
+ * and only exposes packages whose owner has opted in to the public catalog
+ * (`sys_package.marketplace_listed = true`) — so the proxy passes through
+ * without any credentials.
+ *
+ * Why proxy instead of direct browser → cloud:
+ *   - The Console SPA stays on the tenant origin, so no CORS configuration
+ *     is required on the cloud side.
+ *   - Local-dev `os serve` works regardless of whether the developer's
+ *     browser has cookies for cloud.objectos.app.
+ *   - Adds a single, easily auditable network seam between tenant and
+ *     control plane.
+ *
+ * Install is NOT proxied here. Installing a package mutates control-plane
+ * state and requires a cloud session + active organization context — the
+ * Console SPA performs install by opening the cloud's install dialog in a
+ * new tab so the user authenticates against cloud directly. A future
+ * iteration may introduce a delegated install token; until then, browse
+ * here and install on cloud.
+ */
+
+interface MarketplaceProxyPluginConfig {
+    /**
+     * Control-plane base URL (e.g. https://cloud.objectos.app). When the
+     * caller passes nothing AND the runtime has no OS_CLOUD_URL set, the
+     * plugin falls back to the public ObjectStack-operated cloud so that
+     * `objectstack dev` can browse the marketplace out of the box. Set
+     * OS_CLOUD_URL=off (or `local`) to opt out — the plugin then mounts
+     * a stub that responds 503 and the SPA renders an empty-state
+     * explaining marketplace is unavailable in this runtime.
+     */
+    controlPlaneUrl?: string;
+}
+declare class MarketplaceProxyPlugin implements Plugin {
+    readonly name = "com.objectstack.runtime.marketplace-proxy";
+    readonly version = "1.0.0";
+    private readonly cloudUrl;
+    constructor(config?: MarketplaceProxyPluginConfig);
+    init: (_ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+}
+
+interface MarketplaceInstallLocalPluginConfig {
+    /** Cloud control-plane base URL. When unset, falls back to OS_CLOUD_URL
+     *  and then to the public ObjectStack cloud so a fresh `objectstack dev`
+     *  can install from the marketplace without configuration. Set
+     *  OS_CLOUD_URL=off to disable (the install endpoint then returns 503). */
+    controlPlaneUrl?: string;
+    /** Override the on-disk cache directory. Defaults to
+     *  `<cwd>/.objectstack/installed-packages`. */
+    storageDir?: string;
+}
+declare class MarketplaceInstallLocalPlugin implements Plugin {
+    readonly name = "com.objectstack.runtime.marketplace-install-local";
+    readonly version = "1.0.0";
+    private readonly cloudUrl;
+    private readonly storageDir;
+    constructor(config?: MarketplaceInstallLocalPluginConfig);
+    init: (_ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Re-register every cached manifest with the kernel's manifest service.
+     * Safe to call on a kernel that already has the same manifest_id (the
+     * underlying ObjectQL registry overwrites by id, but we still warn so
+     * a developer can spot the dev-time clash between their config.ts and
+     * a marketplace package).
+     */
+    private rehydrate;
+    private handleInstall;
+    private handleList;
+    private handleUninstall;
+    /**
+     * Detect whether `manifestId` is already known to the kernel and classify
+     * the source so we can refuse vs upgrade gracefully.
+     *
+     *   'none'         — fresh install
+     *   'marketplace'  — previously installed by this plugin (allow upgrade)
+     *   'user-code'    — defined by AppPlugin from objectstack.config.ts
+     *                    (refuse to avoid silently overwriting authored code)
+     */
+    private findConflict;
+    /**
+     * Pull a userId out of the request's better-auth session, if any.
+     * Returns null when there is no signed-in user. v1 does not check
+     * admin role — UI gating + the auth requirement is sufficient for
+     * dev / single-tenant runtimes. Stricter checks can be layered on
+     * via a middleware in cloud-hosted multi-tenant deployments.
+     */
+    /**
+     * Replicate the start-time side-effects that AppPlugin runs for
+     * statically-declared apps but the `manifest` service does NOT:
+     *
+     *   1. Load `manifest.translations` (array of `Record<locale, data>`)
+     *      into the i18n service — auto-creating an in-memory fallback if
+     *      none is registered, matching AppPlugin's behaviour.
+     *
+     *   2. Merge `manifest.data` (an array of seed datasets) into the
+     *      kernel's `seed-datasets` service so SecurityPlugin's per-org
+     *      replay middleware picks them up on every future
+     *      sys_organization insert.
+     *
+     *   3. When `seedNow=true`, also run the seed immediately so the user
+     *      sees demo data without having to create a new org:
+     *        • single-tenant: run SeedLoaderService inline (mirrors
+     *          AppPlugin single-tenant branch)
+     *        • multi-tenant: invoke `seed-replayer` for the caller's
+     *          active org (resolved from the request session)
+     *
+     * Errors are logged but never thrown — install succeeds even if
+     * post-register side-effects partially fail (the manifest itself is
+     * already registered + cached). Returns a small summary for the
+     * response envelope.
+     */
+    private applySideEffects;
+    /**
+     * Best-effort active-org resolution. Reads the better-auth session
+     * (same path as requireAuthenticatedUser) and returns
+     * `session.activeOrganizationId`, falling back to the user's first
+     * org membership.
+     */
+    private resolveActiveOrgId;
+    private requireAuthenticatedUser;
+    private readAll;
+}
+
+/**
+ * Shared marketplace / cloud control-plane defaults.
+ *
+ * Centralised so every plugin + the CLI auto-inject path agree on
+ * "what cloud URL do we mean when the user didn't set OS_CLOUD_URL?".
+ * Until we have a competing public hosted cloud, this points at the
+ * ObjectStack-operated control plane so a vanilla `objectstack dev` can
+ * browse the marketplace out of the box.
+ */
+declare const DEFAULT_CLOUD_URL = "https://cloud.objectos.app";
+/**
+ * Resolve the effective control-plane URL from an explicit constructor
+ * value, the OS_CLOUD_URL env var, or the default. Returns an empty
+ * string when the caller explicitly disabled cloud with
+ * `OS_CLOUD_URL=off` / `local` — callers should treat that as
+ * "marketplace unavailable on this runtime".
+ */
+declare function resolveCloudUrl(explicit?: string | null): string;
+
 /**
  * Per-project driver registry contract.
  *
@@ -2227,4 +2459,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveDefaultArtifactPath, resolveRequestId, seedPlatformSsoClient };
+export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveRequestId, seedPlatformSsoClient };

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 import { ObjectKernel, IHttpServer, ObjectKernelConfig, Plugin, PluginContext, RouteHandler, Middleware } from '@objectstack/core';
 export * from '@objectstack/core';
 export { ObjectKernel } from '@objectstack/core';
+import { ClusterServicePluginOptions } from '@objectstack/service-cluster';
+import { ClusterCapabilityConfigInput, ExecutionContext } from '@objectstack/spec/kernel';
 import { z } from 'zod';
 import * as Contracts from '@objectstack/spec/contracts';
 import { ISeedLoaderService, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
 import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Dataset, SeedLoaderConfigInput, ExpressionBody, ScriptBody, HookBody, Hook } from '@objectstack/spec/data';
 import { MetricsRegistry, ErrorReporter } from '@objectstack/observability';
-export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, RUNTIME_METRICS } from '@objectstack/observability';
-import { ExecutionContext } from '@objectstack/spec/kernel';
+export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, OBSERVABILITY_ERRORS_SERVICE, OBSERVABILITY_METRICS_SERVICE, RUNTIME_METRICS } from '@objectstack/observability';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
 import { ProjectArtifact } from '@objectstack/spec/cloud';
 export { RestApiPluginConfig, RestServer, RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin } from '@objectstack/rest';
@@ -23,6 +24,18 @@ interface RuntimeConfig {
      * Kernel Configuration
      */
     kernel?: ObjectKernelConfig;
+    /**
+     * Cluster service configuration.
+     *
+     * - Omit (default): a single-node `memory` cluster is auto-registered.
+     * - `false`: skip auto-registration entirely. Register your own
+     *   `ClusterServicePlugin` if you need it later.
+     * - `ClusterCapabilityConfigInput`: forwarded to `defineCluster()`.
+     * - `{ cluster: IClusterService }`: bring your own instance.
+     *
+     * See `content/docs/concepts/cluster-semantics.mdx` for driver options.
+     */
+    cluster?: false | ClusterCapabilityConfigInput | ClusterServicePluginOptions;
 }
 /**
  * ObjectStack Runtime
@@ -41,6 +54,7 @@ interface RuntimeConfig {
 declare class Runtime {
     readonly kernel: ObjectKernel;
     constructor(config?: RuntimeConfig);
+    private normalizeClusterOptions;
     /**
      * Register a plugin
      */
@@ -61,10 +75,10 @@ declare const StandaloneStackConfigSchema: z.ZodObject<{
     databaseUrl: z.ZodOptional<z.ZodString>;
     databaseAuthToken: z.ZodOptional<z.ZodString>;
     databaseDriver: z.ZodOptional<z.ZodEnum<{
-        sqlite: "sqlite";
-        turso: "turso";
         memory: "memory";
         postgres: "postgres";
+        sqlite: "sqlite";
+        turso: "turso";
         mongodb: "mongodb";
     }>>;
     projectId: z.ZodOptional<z.ZodString>;
@@ -492,6 +506,75 @@ declare function parseTraceparent(value: unknown): TraceContext | undefined;
  */
 declare function formatTraceparent(ctx: TraceContext): string;
 
+/**
+ * Options for {@link ObservabilityServicePlugin}.
+ *
+ * Either or both backends can be omitted; the omitted one resolves to
+ * the corresponding no-op exporter so consumers can always rely on the
+ * service being present.
+ */
+interface ObservabilityServicePluginOptions {
+    /** Metrics backend (e.g. `ConsoleMetricsRegistry`, `OtlpHttpMetricsRegistry`). */
+    metrics?: MetricsRegistry;
+    /** Error reporter backend (e.g. Sentry adapter). */
+    errors?: ErrorReporter;
+}
+/**
+ * `ObservabilityServicePlugin` — registers the host's
+ * {@link MetricsRegistry} and {@link ErrorReporter} in the kernel
+ * service registry under the canonical names so any other plugin can
+ * look them up without each host having to thread observability config
+ * through every plugin constructor.
+ *
+ * Resolution chain other plugins should follow:
+ *
+ *   1. Explicit option on the plugin's own options object (escape
+ *      hatch for tests / explicit wiring).
+ *   2. `ctx.getService(OBSERVABILITY_METRICS_SERVICE)`.
+ *   3. `NoopMetricsRegistry()` — never null.
+ *
+ * Register this plugin **before** any plugin that wants to consume the
+ * services (cache, storage, dispatcher), otherwise the consumer's
+ * `init` will fall through to the no-op default.
+ *
+ * @example
+ * ```ts
+ * import { ObjectKernel } from '@objectstack/core';
+ * import {
+ *   ObservabilityServicePlugin,
+ *   CacheServicePlugin,
+ * } from '@objectstack/runtime';
+ * import { ConsoleMetricsRegistry } from '@objectstack/observability';
+ *
+ * const kernel = new ObjectKernel();
+ * kernel.use(new ObservabilityServicePlugin({
+ *   metrics: new ConsoleMetricsRegistry(),
+ * }));
+ * kernel.use(new CacheServicePlugin()); // picks metrics up automatically
+ * ```
+ */
+declare class ObservabilityServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: string;
+    private readonly options;
+    constructor(options?: ObservabilityServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+}
+/**
+ * Helper used by consumer plugins to resolve a metrics backend with
+ * the canonical fallback chain. Never throws; always returns a usable
+ * `MetricsRegistry`.
+ *
+ * @param ctx        the consuming plugin's `PluginContext`
+ * @param override   explicit option set on the consuming plugin (wins)
+ */
+declare function resolveMetrics(ctx: PluginContext, override?: MetricsRegistry): MetricsRegistry;
+/**
+ * Sibling of {@link resolveMetrics} for {@link ErrorReporter}.
+ */
+declare function resolveErrorReporter(ctx: PluginContext, override?: ErrorReporter): ErrorReporter;
+
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -1745,6 +1828,155 @@ interface ObjectOSStackResult {
 }
 declare function createObjectOSStack(config: ObjectOSStackConfig): Promise<ObjectOSStackResult>;
 
+/**
+ * MarketplaceProxyPlugin
+ *
+ * Forwards `GET /api/v1/marketplace/*` from a tenant ObjectOS runtime to
+ * the configured ObjectStack Cloud control-plane URL. The cloud endpoint
+ * (`packages/service-cloud/src/routes/marketplace.ts`) is unauthenticated
+ * and only exposes packages whose owner has opted in to the public catalog
+ * (`sys_package.marketplace_listed = true`) — so the proxy passes through
+ * without any credentials.
+ *
+ * Why proxy instead of direct browser → cloud:
+ *   - The Console SPA stays on the tenant origin, so no CORS configuration
+ *     is required on the cloud side.
+ *   - Local-dev `os serve` works regardless of whether the developer's
+ *     browser has cookies for cloud.objectos.app.
+ *   - Adds a single, easily auditable network seam between tenant and
+ *     control plane.
+ *
+ * Install is NOT proxied here. Installing a package mutates control-plane
+ * state and requires a cloud session + active organization context — the
+ * Console SPA performs install by opening the cloud's install dialog in a
+ * new tab so the user authenticates against cloud directly. A future
+ * iteration may introduce a delegated install token; until then, browse
+ * here and install on cloud.
+ */
+
+interface MarketplaceProxyPluginConfig {
+    /**
+     * Control-plane base URL (e.g. https://cloud.objectos.app). When the
+     * caller passes nothing AND the runtime has no OS_CLOUD_URL set, the
+     * plugin falls back to the public ObjectStack-operated cloud so that
+     * `objectstack dev` can browse the marketplace out of the box. Set
+     * OS_CLOUD_URL=off (or `local`) to opt out — the plugin then mounts
+     * a stub that responds 503 and the SPA renders an empty-state
+     * explaining marketplace is unavailable in this runtime.
+     */
+    controlPlaneUrl?: string;
+}
+declare class MarketplaceProxyPlugin implements Plugin {
+    readonly name = "com.objectstack.runtime.marketplace-proxy";
+    readonly version = "1.0.0";
+    private readonly cloudUrl;
+    constructor(config?: MarketplaceProxyPluginConfig);
+    init: (_ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+}
+
+interface MarketplaceInstallLocalPluginConfig {
+    /** Cloud control-plane base URL. When unset, falls back to OS_CLOUD_URL
+     *  and then to the public ObjectStack cloud so a fresh `objectstack dev`
+     *  can install from the marketplace without configuration. Set
+     *  OS_CLOUD_URL=off to disable (the install endpoint then returns 503). */
+    controlPlaneUrl?: string;
+    /** Override the on-disk cache directory. Defaults to
+     *  `<cwd>/.objectstack/installed-packages`. */
+    storageDir?: string;
+}
+declare class MarketplaceInstallLocalPlugin implements Plugin {
+    readonly name = "com.objectstack.runtime.marketplace-install-local";
+    readonly version = "1.0.0";
+    private readonly cloudUrl;
+    private readonly storageDir;
+    constructor(config?: MarketplaceInstallLocalPluginConfig);
+    init: (_ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Re-register every cached manifest with the kernel's manifest service.
+     * Safe to call on a kernel that already has the same manifest_id (the
+     * underlying ObjectQL registry overwrites by id, but we still warn so
+     * a developer can spot the dev-time clash between their config.ts and
+     * a marketplace package).
+     */
+    private rehydrate;
+    private handleInstall;
+    private handleList;
+    private handleUninstall;
+    /**
+     * Detect whether `manifestId` is already known to the kernel and classify
+     * the source so we can refuse vs upgrade gracefully.
+     *
+     *   'none'         — fresh install
+     *   'marketplace'  — previously installed by this plugin (allow upgrade)
+     *   'user-code'    — defined by AppPlugin from objectstack.config.ts
+     *                    (refuse to avoid silently overwriting authored code)
+     */
+    private findConflict;
+    /**
+     * Pull a userId out of the request's better-auth session, if any.
+     * Returns null when there is no signed-in user. v1 does not check
+     * admin role — UI gating + the auth requirement is sufficient for
+     * dev / single-tenant runtimes. Stricter checks can be layered on
+     * via a middleware in cloud-hosted multi-tenant deployments.
+     */
+    /**
+     * Replicate the start-time side-effects that AppPlugin runs for
+     * statically-declared apps but the `manifest` service does NOT:
+     *
+     *   1. Load `manifest.translations` (array of `Record<locale, data>`)
+     *      into the i18n service — auto-creating an in-memory fallback if
+     *      none is registered, matching AppPlugin's behaviour.
+     *
+     *   2. Merge `manifest.data` (an array of seed datasets) into the
+     *      kernel's `seed-datasets` service so SecurityPlugin's per-org
+     *      replay middleware picks them up on every future
+     *      sys_organization insert.
+     *
+     *   3. When `seedNow=true`, also run the seed immediately so the user
+     *      sees demo data without having to create a new org:
+     *        • single-tenant: run SeedLoaderService inline (mirrors
+     *          AppPlugin single-tenant branch)
+     *        • multi-tenant: invoke `seed-replayer` for the caller's
+     *          active org (resolved from the request session)
+     *
+     * Errors are logged but never thrown — install succeeds even if
+     * post-register side-effects partially fail (the manifest itself is
+     * already registered + cached). Returns a small summary for the
+     * response envelope.
+     */
+    private applySideEffects;
+    /**
+     * Best-effort active-org resolution. Reads the better-auth session
+     * (same path as requireAuthenticatedUser) and returns
+     * `session.activeOrganizationId`, falling back to the user's first
+     * org membership.
+     */
+    private resolveActiveOrgId;
+    private requireAuthenticatedUser;
+    private readAll;
+}
+
+/**
+ * Shared marketplace / cloud control-plane defaults.
+ *
+ * Centralised so every plugin + the CLI auto-inject path agree on
+ * "what cloud URL do we mean when the user didn't set OS_CLOUD_URL?".
+ * Until we have a competing public hosted cloud, this points at the
+ * ObjectStack-operated control plane so a vanilla `objectstack dev` can
+ * browse the marketplace out of the box.
+ */
+declare const DEFAULT_CLOUD_URL = "https://cloud.objectos.app";
+/**
+ * Resolve the effective control-plane URL from an explicit constructor
+ * value, the OS_CLOUD_URL env var, or the default. Returns an empty
+ * string when the caller explicitly disabled cloud with
+ * `OS_CLOUD_URL=off` / `local` — callers should treat that as
+ * "marketplace unavailable on this runtime".
+ */
+declare function resolveCloudUrl(explicit?: string | null): string;
+
 /**
  * Per-project driver registry contract.
  *
@@ -2227,4 +2459,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveDefaultArtifactPath, resolveRequestId, seedPlatformSsoClient };
+export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveRequestId, seedPlatformSsoClient };