@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/extensions/extensions.module.js

@@ -0,0 +1,96 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { SuperAdminLockModule } from "../identity/super-admin.js";
+import { ModelsModule } from "../models/models.module.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { EmbedTokensModule } from "../ui/embed-token.js";
+import { ExtensionAdminOps } from "./admin-ops.js";
+import { ExtensionAdmin } from "./admin-view.js";
+import { BootstrapService } from "./bootstrap.js";
+import { ExtensionDeploymentConfigService } from "./deployment-config.js";
+import { ExtensionDisplayNames } from "./display-name.js";
+import { ExtensionHost } from "./host.js";
+import { ExtensionLifecycle } from "./lifecycle.js";
+import { PluginApproveLock, PluginDeploymentConfigLock, PluginInstallLock, SingleProviderLock, } from "./locks.js";
+import { OrgExtensionConfigs } from "./org-config.js";
+import { OrgOverrides } from "./org-overrides.js";
+import { PluginGuides } from "./plugin-guides.js";
+import { PluginIcons } from "./plugin-icons.js";
+import { ExtensionPointDefaults } from "./point-defaults.js";
+import { ExtensionRegistryModule } from "./registry.js";
+import { SingleProviderGuard } from "./single-provider.js";
+import { ReplicaStatusStore } from "./sources.js";
+import { ExtensionStateModule } from "./state.module.js";
+import { ExtensionAvailability } from "./unavailable.js";
+/**
+ * The extensions domain: the extension host (it builds each `ctx` from the injected kernel
+ * services), the package store and install records (the desired state the host converges to, one
+ * way: spec §3), the per-replica lifecycle and its periodic reconcile, the admin operations,
+ * deployment and org configs, the bootstrap step, and the shared {@link ExtensionRegistry}.
+ */
+let ExtensionsModule = class ExtensionsModule {
+};
+ExtensionsModule = __decorate([
+    Module({
+        imports: [
+            ExtensionRegistryModule,
+            SuperAdminLockModule,
+            OrgLockModule,
+            StorageModule,
+            // ctx.ui verifies embed tokens with the one provider the UI routes issue them with
+            EmbedTokensModule,
+            ExtensionStateModule,
+            // ctx.models: the embeddings broker (models domain, below the host through ExtensionStateModule)
+            ModelsModule,
+        ],
+        providers: [
+            PluginInstallLock,
+            PluginApproveLock,
+            PluginDeploymentConfigLock,
+            SingleProviderLock,
+            SingleProviderGuard,
+            ReplicaStatusStore,
+            ExtensionHost,
+            ExtensionLifecycle,
+            ExtensionAdmin,
+            ExtensionAdminOps,
+            ExtensionDisplayNames,
+            PluginIcons,
+            PluginGuides,
+            ExtensionDeploymentConfigService,
+            OrgExtensionConfigs,
+            OrgOverrides,
+            ExtensionPointDefaults,
+            BootstrapService,
+            ExtensionAvailability,
+        ],
+        exports: [
+            ExtensionRegistryModule,
+            ExtensionStateModule,
+            PluginInstallLock,
+            PluginApproveLock,
+            ReplicaStatusStore,
+            ExtensionHost,
+            ExtensionLifecycle,
+            ExtensionAdmin,
+            ExtensionAdminOps,
+            ExtensionDisplayNames,
+            PluginIcons,
+            PluginGuides,
+            ExtensionDeploymentConfigService,
+            OrgExtensionConfigs,
+            OrgOverrides,
+            ExtensionPointDefaults,
+            BootstrapService,
+            ExtensionAvailability,
+            SingleProviderGuard,
+        ],
+    })
+], ExtensionsModule);
+export { ExtensionsModule };

package/dist/extensions/hooks.d.ts

@@ -1,6 +1,7 @@
 import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type Logger, type PolicyHook } from "@capybara-hq/plugin-sdk";
-import type { Redis } from "ioredis";
 import type { KernelConfig } from "../config/schema.js";
+import type { LockService } from "../infra/lock/lock.service.js";
+import { type EffectiveConfig } from "./effective-config.js";
 import { type InflightTracker } from "./inflight.js";
 /** Default of `hooks.timeoutMs` (used when a host is built without kernel config, e.g. in tests). */
 export declare const DEFAULT_HOOK_TIMEOUT_MS = 5000;
@@ -27,8 +28,8 @@ export type HookOutcome = {
     cause: "deny" | "hook_error" | "timeout";
     detail?: string;
     /**
-     * R10: the hooks could not run at all (organization lookup or payload copy failed); `plugin` is
-     * only the first policy plugin on the mount, not the cause.
+     * R10: the hooks could not run at all (organization lookup, config read or payload copy
+     * failed); `plugin` is only the first policy plugin on the mount, not the cause.
      */
     preflight?: true;
     /**
@@ -36,7 +37,21 @@ export type HookOutcome = {
      * approved, but is not loaded on this replica: the call fails closed without running any hook.
      */
     notLoaded?: true;
+    /**
+     * Layering spec A §6: `plugin` has a policy hook on this mount but its effective config is not
+     * valid in the organization, so it behaves as if not loaded: the call fails closed without
+     * running any policy hook.
+     */
+    needsConfig?: true;
 };
+/**
+ * Thrown by a `usage.report` handler wrapper (see {@link HookRegistry.handlers}) instead of calling
+ * a handler whose extension's effective config is not valid in the payload's organization.
+ */
+export declare class HookNeedsConfigError extends Error {
+    readonly plugin: string;
+    constructor(plugin: string);
+}
 /** A hook a plugin instance registered through `ctx.hooks.on` (kept on the instance, like tools). */
 export interface RegisteredHook {
     mount: AvailableHook;
@@ -80,7 +95,12 @@ export declare const HOOK_DETAIL_MAX_CHARS = 2048;
  *    If a plugin the organization enabled is expected to run policy hooks on the mount (deployment
  *    state, `expectedPolicy`) but is not loaded on this replica, deny with a generic reason
  *    (`hook_error`, `notLoaded`) without running any policy hook (M-1: fail closed). Observe hooks
- *    of plugins that are not loaded are simply missing.
+ *    of plugins that are not loaded are simply missing. Then each enabled plugin with a hook on the
+ *    mount gets its effective config for the organization (layering spec A §6; one read per plugin
+ *    and call, failing like the lookup above). A plugin whose config is not valid behaves as one
+ *    that is not loaded: with a policy hook on the mount the call is denied (`hook_error`,
+ *    `needsConfig`) without running any policy hook, and its observe hooks are skipped. Every
+ *    hook is called with `{ config }` as its third argument.
  * 3. Policy hooks run serially by plugin name (registration order within a plugin), each limited
  *    by `hooks.timeoutMs` (read on every run, hot). `{ deny }`, an error or a timeout stops the chain
  *    and denies (`deny` / `hook_error` / `timeout`). A policy hook cut off by its instance being
@@ -112,7 +132,14 @@ export declare class HookRegistry {
          */
         expectedPolicy?(mount: PolicyHook): readonly string[];
         enabledPlugins(orgId: string): Promise<Set<string>>;
-        redis: Redis;
+        /**
+         * The effective deployment config of a plugin for an organization (`EffectiveConfigs.get`):
+         * passed to every hook call, and no hook of the plugin runs for the organization when it is
+         * not valid.
+         */
+        effectiveConfig(orgId: string, plugin: string): Promise<EffectiveConfig>;
+        /** The warn-once markers (`lease`: set unless present, with a TTL). */
+        locks: Pick<LockService, "lease">;
         config: () => {
             hooks: Pick<KernelConfig["hooks"], "timeoutMs">;
         };
@@ -131,7 +158,9 @@ export declare class HookRegistry {
     private unloadedPolicy;
     /**
      * `usage.report` handlers by plugin name (delivered by the usage queue, not by {@link run}); each
-     * call runs through the instance's `inflight.run`.
+     * call runs through the instance's `inflight.run` with the plugin's effective config for the
+     * payload's organization, and throws {@link HookNeedsConfigError} without calling the handler
+     * when that config is not valid (layering spec A §6).
      */
     handlers(mount: "usage.report"): {
         plugin: string;
@@ -145,6 +174,11 @@ export declare class HookRegistry {
      * admin.
      */
     private notLoadedDenial;
+    /**
+     * The layering spec A §6 denial: `needy` (sorted) are enabled policy plugins whose effective
+     * config is not valid in the organization. Generic model-visible reason, as for M-1.
+     */
+    private needsConfigDenial;
     /** Active entries of a mount point, sorted by plugin name (stable: registration order within). */
     private entries;
     /** One plugin's policy hooks in registration order; reruns once on a newer generation if revoked. */

package/dist/extensions/hooks.js

@@ -1,4 +1,5 @@
 import { HOOKS_AVAILABLE, POLICY_HOOKS, } from "@capybara-hq/plugin-sdk";
+import { NEEDS_CONFIG_REASON } from "./effective-config.js";
 import { ExtensionUnloadedError } from "./inflight.js";
 /** Default of `hooks.timeoutMs` (used when a host is built without kernel config, e.g. in tests). */
 export const DEFAULT_HOOK_TIMEOUT_MS = 5000;
@@ -13,6 +14,18 @@ export const OBSERVE_INFLIGHT_MAX = 64;
 export const EMPTY_DENY_REASON = "(no reason given)";
 /** Warnings about a plugin's hooks are logged at most once per plugin, mount and kind in this window. */
 const WARN_WINDOW_MS = 60_000;
+/**
+ * Thrown by a `usage.report` handler wrapper (see {@link HookRegistry.handlers}) instead of calling
+ * a handler whose extension's effective config is not valid in the payload's organization.
+ */
+export class HookNeedsConfigError extends Error {
+    plugin;
+    constructor(plugin) {
+        super(`extension ${plugin} ${NEEDS_CONFIG_REASON}`);
+        this.plugin = plugin;
+        this.name = "HookNeedsConfigError";
+    }
+}
 const AVAILABLE = new Set(HOOKS_AVAILABLE);
 const POLICY = new Set(POLICY_HOOKS);
 /** Error text that never throws itself (a hostile `message` getter or `toString`). */
@@ -110,7 +123,12 @@ const clipDetail = (s) => clipText(s, HOOK_DETAIL_MAX_CHARS);
  *    If a plugin the organization enabled is expected to run policy hooks on the mount (deployment
  *    state, `expectedPolicy`) but is not loaded on this replica, deny with a generic reason
  *    (`hook_error`, `notLoaded`) without running any policy hook (M-1: fail closed). Observe hooks
- *    of plugins that are not loaded are simply missing.
+ *    of plugins that are not loaded are simply missing. Then each enabled plugin with a hook on the
+ *    mount gets its effective config for the organization (layering spec A §6; one read per plugin
+ *    and call, failing like the lookup above). A plugin whose config is not valid behaves as one
+ *    that is not loaded: with a policy hook on the mount the call is denied (`hook_error`,
+ *    `needsConfig`) without running any policy hook, and its observe hooks are skipped. Every
+ *    hook is called with `{ config }` as its third argument.
  * 3. Policy hooks run serially by plugin name (registration order within a plugin), each limited
  *    by `hooks.timeoutMs` (read on every run, hot). `{ deny }`, an error or a timeout stops the chain
  *    and denies (`deny` / `hook_error` / `timeout`). A policy hook cut off by its instance being
@@ -156,13 +174,18 @@ export class HookRegistry {
     }
     /**
      * `usage.report` handlers by plugin name (delivered by the usage queue, not by {@link run}); each
-     * call runs through the instance's `inflight.run`.
+     * call runs through the instance's `inflight.run` with the plugin's effective config for the
+     * payload's organization, and throws {@link HookNeedsConfigError} without calling the handler
+     * when that config is not valid (layering spec A §6).
      */
     handlers(mount) {
         return this.entries(mount).map(({ src, hook }) => ({
             plugin: src.name,
             handler: (payload, signal) => src.inflight.run(signal, async (s) => {
-                await hook.handler(payload, s);
+                const effective = await this.d.effectiveConfig(payload.orgId, src.name);
+                if (!effective.ok)
+                    throw new HookNeedsConfigError(src.name);
+                await hook.handler(payload, s, { config: effective.config });
             }),
         }));
     }
@@ -177,6 +200,8 @@ export class HookRegistry {
         let enabled;
         let frozen;
         let missing;
+        /** Effective config per enabled plugin with a hook here; null = not valid in the org. */
+        const configs = new Map();
         try {
             const abort = abortOf(signal);
             try {
@@ -194,6 +219,19 @@ export class HookRegistry {
             }
             if (!all.some((e) => enabled.has(e.src.name)))
                 return { allowed: true };
+            for (const name of new Set(all.map((e) => e.src.name).filter((n) => enabled.has(n)))) {
+                const abortCfg = abortOf(signal);
+                try {
+                    const e = await Promise.race([
+                        this.d.effectiveConfig(payload.orgId, name),
+                        abortCfg.aborted,
+                    ]);
+                    configs.set(name, e.ok ? { config: e.config } : null);
+                }
+                finally {
+                    abortCfg.cleanup();
+                }
+            }
             // Cost: one clone + deep-freeze per call. The model.request payload carries no media bytes
             // (hookRequestOf, I-3), so it stays small. Freezing in place would freeze the logged object.
             // The clone is skipped when has() is false or no enabled plugin has a hook on this mount.
@@ -207,7 +245,7 @@ export class HookRegistry {
             if (firstPolicy !== undefined) {
                 // R10: no plugin ran; the named plugin is only the first policy plugin on this mount, so
                 // the detail says so instead of blaming it
-                const detail = clipDetail(`Hooks could not run (organization lookup or payload copy failed) before any plugin was called; ${firstPolicy} is named only as the first policy plugin on ${mount}: ${raw}`);
+                const detail = clipDetail(`Hooks could not run (organization lookup, config read or payload copy failed) before any plugin was called; ${firstPolicy} is named only as the first policy plugin on ${mount}: ${raw}`);
                 this.d.log.warn("plugin hooks could not run; denying the call", {
                     mount,
                     firstPolicyPlugin: firstPolicy,
@@ -227,9 +265,19 @@ export class HookRegistry {
             }
             return { allowed: true };
         }
-        const active = all.filter((e) => enabled.has(e.src.name));
+        const active = all.filter((e) => enabled.has(e.src.name) && configs.get(e.src.name));
         const timeoutMs = this.d.config().hooks.timeoutMs;
-        let outcome = missing.length > 0 ? this.notLoadedDenial(mount, missing) : { allowed: true };
+        // spec A §6: a policy plugin without a valid config in the org behaves as one not loaded
+        const needy = [
+            ...new Set(all
+                .filter((e) => e.hook.mode === "policy" && configs.get(e.src.name) === null)
+                .map((e) => e.src.name)),
+        ];
+        let outcome = missing.length > 0
+            ? this.notLoadedDenial(mount, missing)
+            : needy.length > 0
+                ? this.needsConfigDenial(mount, needy)
+                : { allowed: true };
         // policy hooks grouped per plugin (entries are sorted, so groups are contiguous)
         const groups = [];
         for (const e of active) {
@@ -242,7 +290,8 @@ export class HookRegistry {
                 groups.push({ src: e.src, hooks: [e.hook] });
         }
         for (const g of outcome.allowed ? groups : []) {
-            const denied = await this.runPolicies(mount, g.src, g.hooks, frozen, signal, timeoutMs);
+            const call = configs.get(g.src.name);
+            const denied = await this.runPolicies(mount, g.src, g.hooks, frozen, call, signal, timeoutMs);
             if (denied) {
                 outcome = denied;
                 break;
@@ -251,8 +300,10 @@ export class HookRegistry {
         // observe hooks are resolved again now: if the plugin was upgraded while the policy hooks ran,
         // the current generation observes (the retiring one no longer accepts calls)
         for (const e of this.entries(mount)) {
-            if (e.hook.mode === "observe" && enabled.has(e.src.name)) {
-                this.dispatchObserve(mount, e.src, e.hook, frozen, signal);
+            const call = configs.get(e.src.name);
+            // no config read for it (not valid in the org, or a plugin that appeared meanwhile): skipped
+            if (e.hook.mode === "observe" && enabled.has(e.src.name) && call) {
+                this.dispatchObserve(mount, e.src, e.hook, frozen, call, signal);
             }
         }
         return outcome;
@@ -277,6 +328,21 @@ export class HookRegistry {
             notLoaded: true,
         };
     }
+    /**
+     * The layering spec A §6 denial: `needy` (sorted) are enabled policy plugins whose effective
+     * config is not valid in the organization. Generic model-visible reason, as for M-1.
+     */
+    needsConfigDenial(mount, needy) {
+        const plugin = needy[0];
+        return {
+            allowed: false,
+            plugin,
+            reason: unavailableReason(plugin),
+            cause: "hook_error",
+            detail: `extension ${needy.join(", ")} declares a policy hook on ${mount} but ${NEEDS_CONFIG_REASON}; the call was denied without running any policy hook`,
+            needsConfig: true,
+        };
+    }
     /** Active entries of a mount point, sorted by plugin name (stable: registration order within). */
     entries(mount) {
         return this.d
@@ -285,14 +351,14 @@ export class HookRegistry {
             .sort((a, b) => (a.src.name < b.src.name ? -1 : a.src.name > b.src.name ? 1 : 0));
     }
     /** One plugin's policy hooks in registration order; reruns once on a newer generation if revoked. */
-    async runPolicies(mount, src, hooks, payload, signal, timeoutMs, rerun = false) {
+    async runPolicies(mount, src, hooks, payload, call, signal, timeoutMs, rerun = false) {
         const plugin = src.name;
         for (const hook of hooks) {
             if (signal.aborted)
                 throw signal.reason;
             let r;
             try {
-                r = await src.inflight.run(signal, (s) => this.call(hook, payload, s, timeoutMs));
+                r = await src.inflight.run(signal, (s) => this.call(hook, payload, call, s, timeoutMs));
             }
             catch (err) {
                 if (signal.aborted)
@@ -301,7 +367,7 @@ export class HookRegistry {
                     const cur = this.d.current(plugin);
                     if (!rerun && cur && cur !== src) {
                         const again = cur.hooks.filter((h) => h.mount === mount && h.mode === "policy");
-                        return this.runPolicies(mount, cur, again, payload, signal, timeoutMs, true);
+                        return this.runPolicies(mount, cur, again, payload, call, signal, timeoutMs, true);
                     }
                 }
                 r = { kind: "error", message: errMsg(err) };
@@ -338,7 +404,7 @@ export class HookRegistry {
         return undefined;
     }
     /** Fire-and-forget observe call through the instance's in-flight tracker, capped per plugin. */
-    dispatchObserve(mount, src, hook, payload, signal) {
+    dispatchObserve(mount, src, hook, payload, call, signal) {
         const plugin = src.name;
         const n = this.observing.get(plugin) ?? 0;
         if (n >= OBSERVE_INFLIGHT_MAX) {
@@ -349,7 +415,7 @@ export class HookRegistry {
         this.observing.set(plugin, n + 1);
         void (async () => {
             try {
-                const r = await src.inflight.run(signal, (s) => this.call(hook, payload, s, timeoutMs));
+                const r = await src.inflight.run(signal, (s) => this.call(hook, payload, call, s, timeoutMs));
                 if (r.kind === "error" || r.kind === "timeout") {
                     await this.warnOnce(plugin, mount, "failed", "plugin observe hook failed; the call continued", r.kind === "timeout" ? `timed out after ${timeoutMs} ms` : r.message);
                 }
@@ -371,7 +437,7 @@ export class HookRegistry {
      * Calls one handler with its own signal (aborted on timeout or when `s` aborts). Rejects with
      * `s.reason` when `s` aborts first, so callers can tell an abort from a hook failure.
      */
-    async call(hook, payload, s, timeoutMs) {
+    async call(hook, payload, call, s, timeoutMs) {
         const ac = new AbortController();
         const onAbort = () => ac.abort(s.reason);
         if (s.aborted)
@@ -385,7 +451,7 @@ export class HookRegistry {
                 timer = setTimeout(() => resolve("timeout"), timeoutMs);
             });
             const handled = Promise.resolve()
-                .then(() => hook.handler(payload, ac.signal))
+                .then(() => hook.handler(payload, ac.signal, { config: call.config }))
                 .then((v) => ({ v }), (err) => ({ err }));
             const result = await Promise.race([handled, timedOut, abort.aborted]);
             if (result === "timeout") {
@@ -414,7 +480,7 @@ export class HookRegistry {
         const key = `capk:hook-warn:${plugin}:${mount}:${kind}`;
         let first = true;
         try {
-            first = (await this.d.redis.set(key, "1", "PX", WARN_WINDOW_MS, "NX")) === "OK";
+            first = await this.d.locks.lease(key, "1", WARN_WINDOW_MS);
         }
         catch {
             // Redis unavailable: log anyway rather than hiding the failure