@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/extensions/lifecycle-hooks.js

@@ -0,0 +1,273 @@
+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;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { OnWorkerEvent, Processor, WorkerHost } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { runJob } from "../infra/queue/run-job.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ExtensionsModule } from "./extensions.module.js";
+import { deepFreeze, errMsg } from "./hooks.js";
+import { ExtensionHost } from "./host.js";
+/** Queue of lifecycle hook deliveries (no `:` in the name). */
+export const LIFECYCLE_QUEUE = "cap-kernel-lifecycle";
+/** The job name of every delivery (registered in `infra/outbox/registry.ts`). */
+export const LIFECYCLE_JOB = "lifecycle";
+/** One handler call's time limit. */
+export const LIFECYCLE_HOOK_TIMEOUT_MS = 5000;
+/** Concurrent deliveries per worker replica. */
+const LIFECYCLE_CONCURRENCY = 4;
+/**
+ * The deterministic job id of one delivery: the mount, the plugin and the payload's ids (no `:`;
+ * kernel ids and plugin names carry none). Removing the same member, agent or org again while the
+ * first delivery is still owed is the same job.
+ */
+export function lifecycleJobId(mount, plugin, payload) {
+    const ids = Object.entries(payload)
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([, v]) => String(v));
+    return ["lifecycle", mount.replaceAll(".", "-"), plugin, ...ids].join("-").replaceAll(":", "-");
+}
+/**
+ * Plugins that subscribe to a lifecycle mount according to deployment state: the approved
+ * permission snapshot declares the mount in `permissions.hooks`, and that approved version is the
+ * one the deployment runs: an enabled install of that version, or a replica status row (not
+ * `unloaded`) that loaded or still serves it (an upgrade pending approval keeps serving the
+ * approved version; a config-declared plugin has only replica rows). A snapshot approved for
+ * another version than the one installed or served does not count. Org enablement does not count
+ * either: cleanup concerns data the plugin already holds (memory plugin spec §6.3). Sorted by name.
+ */
+export async function queryLifecycleSubscribers(db, mount) {
+    const rows = await db
+        .selectFrom("extension_permission_snapshots as s")
+        .select("s.plugin")
+        .distinct()
+        .where(sql `s.permissions -> 'permissions' -> 'hooks' ? ${mount}`)
+        .where((eb) => eb.or([
+        eb.exists(eb
+            .selectFrom("extension_installs as i")
+            .select(sql `1`.as("one"))
+            .whereRef("i.name", "=", "s.plugin")
+            .whereRef("i.version", "=", "s.version")
+            .where("i.desired_state", "=", "enabled")),
+        eb.exists(eb
+            .selectFrom("extension_replica_status as r")
+            .select(sql `1`.as("one"))
+            .whereRef("r.plugin", "=", "s.plugin")
+            .where("r.state", "<>", "unloaded")
+            .where((r) => r.or([
+            r("r.version", "=", r.ref("s.version")),
+            r("r.serving_version", "=", r.ref("s.version")),
+        ]))),
+    ]))
+        .orderBy("s.plugin")
+        .execute();
+    return rows.map((r) => r.plugin);
+}
+/**
+ * Durable delivery of the lifecycle hooks `org.member_removed`, `agent.deleted` and `org.deleted`
+ * (memory plugin spec §6.3), so extensions reliably learn to delete the data they hold:
+ * - **Owe** ({@link recordIn}): in the transaction that removes the member, the agent or the org,
+ *   one outbox job per subscribing plugin ({@link queryLifecycleSubscribers}) on
+ *   {@link LIFECYCLE_QUEUE}, under {@link lifecycleJobId}, with no `org_id` (it is the deletion's
+ *   own cleanup work, transactional outbox spec §9); a rollback owes nothing. The outbox delivers
+ *   it to BullMQ after the commit (registry: attempts and backoff).
+ * - **Deliver** ({@link process}, worker role): the plugin's handlers loaded on this replica are
+ *   called in turn (5 s each). Not loaded on this replica -> the job fails and is retried (another
+ *   replica or a later attempt). Loaded without a handler -> dropped with a warning. Handlers get
+ *   the plugin's platform deployment config (`call.config`), never an org's copy, so an org whose
+ *   effective config is not valid still gets its cleanup. The last failed attempt logs an error.
+ * Handlers must be idempotent (a delivery may repeat when a replica dies after the call).
+ */
+let LifecycleHooks = class LifecycleHooks {
+    kdb;
+    txHost;
+    outbox;
+    host;
+    log;
+    constructor(kdb, txHost, outbox, 
+    /** The loaded plugins' handlers (`hooks.handlers`) and whether a plugin is active here. */
+    host, log) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.outbox = outbox;
+        this.host = host;
+        this.log = log;
+    }
+    /**
+     * Owes one delivery per subscribing plugin in the caller's transaction (`mandatory`); returns
+     * the plugins.
+     */
+    async recordIn(mount, payload) {
+        const plugins = await queryLifecycleSubscribers(this.kdb.db, mount);
+        for (const plugin of plugins) {
+            const data = { mount, plugin, payload };
+            await this.outbox.add({
+                queue: LIFECYCLE_QUEUE,
+                name: LIFECYCLE_JOB,
+                jobId: lifecycleJobId(mount, plugin, payload),
+                data,
+            });
+        }
+        return plugins;
+    }
+    /** One delivery job (the consumer {@link LifecycleHooksProcessor} calls it). */
+    async process(data, stop) {
+        const fields = { mount: data.mount, plugin: data.plugin };
+        const handlers = this.host.hooks
+            .lifecycleHandlers(data.mount)
+            .filter((h) => h.plugin === data.plugin)
+            .map((h) => h.handler);
+        if (handlers.length === 0) {
+            if (this.host.current(data.plugin) === undefined) {
+                // another replica or a later attempt may have it loaded
+                throw new Error(`plugin ${data.plugin} is not loaded on this replica`);
+            }
+            this.log.warn("lifecycle hook delivery dropped: the plugin registered no handler", fields);
+            return;
+        }
+        const payload = deepFreeze(structuredClone(data.payload));
+        for (const h of handlers)
+            await this.call(h, payload, stop);
+    }
+    /** One handler call, aborted after {@link LIFECYCLE_HOOK_TIMEOUT_MS} or when the replica stops. */
+    async call(h, payload, stop) {
+        const ac = new AbortController();
+        const onStop = () => ac.abort(new Error("replica stopping"));
+        if (stop.aborted)
+            onStop();
+        else
+            stop.addEventListener("abort", onStop, { once: true });
+        let timer;
+        try {
+            await Promise.race([
+                Promise.resolve().then(() => h(payload, ac.signal)),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        const err = new Error(`timed out after ${LIFECYCLE_HOOK_TIMEOUT_MS} ms`);
+                        ac.abort(err);
+                        reject(err);
+                    }, LIFECYCLE_HOOK_TIMEOUT_MS);
+                    // already aborted (the replica was stopping before the call): no abort event will fire
+                    if (ac.signal.aborted)
+                        reject(ac.signal.reason);
+                    else
+                        ac.signal.addEventListener("abort", () => reject(ac.signal.reason), { once: true });
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            stop.removeEventListener("abort", onStop);
+        }
+    }
+    /** A job failed (the worker's `failed` event): a retry warns, the last attempt logs an error. */
+    onFailed(j, err) {
+        if (!j)
+            return;
+        const fields = {
+            jobId: j.id,
+            mount: j.data.mount,
+            plugin: j.data.plugin,
+            attempt: j.attemptsMade,
+            error: errMsg(err),
+        };
+        if (j.attemptsMade >= (j.opts.attempts ?? 1)) {
+            this.log.error("lifecycle hook delivery failed on its last attempt; given up", fields);
+        }
+        else
+            this.log.warn("lifecycle hook delivery failed; retrying", fields);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], LifecycleHooks.prototype, "recordIn", null);
+LifecycleHooks = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(OutboxService)),
+    __param(3, Inject(ExtensionHost)),
+    __param(4, Inject(KERNEL_LOGGER))
+], LifecycleHooks);
+export { LifecycleHooks };
+/**
+ * The consumer of {@link LIFECYCLE_QUEUE}: {@link LifecycleHooks.process}. Worker role only
+ * (`LifecycleHookWorkersModule`); built with `autorun: false`, started by the worker role after the
+ * extensions loaded.
+ */
+let LifecycleHooksProcessor = class LifecycleHooksProcessor extends WorkerHost {
+    hooks;
+    log;
+    stopping = new AbortController();
+    constructor(hooks, log) {
+        super();
+        this.hooks = hooks;
+        this.log = log;
+    }
+    process(job) {
+        return runJob(LIFECYCLE_QUEUE, job, () => this.hooks.process(job.data, this.stopping.signal));
+    }
+    /** Starts consuming (worker role, after the extensions loaded). */
+    start() {
+        void this.worker.run().catch((err) => this.error(err));
+    }
+    /** Aborts the calls in flight and closes the worker. */
+    async close() {
+        this.stopping.abort();
+        await this.worker.close();
+    }
+    failed(job, err) {
+        this.hooks.onFailed(job, err);
+    }
+    error(err) {
+        this.log.error("lifecycle hook worker error", { err });
+    }
+};
+__decorate([
+    OnWorkerEvent("failed")
+], LifecycleHooksProcessor.prototype, "failed", null);
+__decorate([
+    OnWorkerEvent("error")
+], LifecycleHooksProcessor.prototype, "error", null);
+LifecycleHooksProcessor = __decorate([
+    Injectable(),
+    Processor(LIFECYCLE_QUEUE, { autorun: false, concurrency: LIFECYCLE_CONCURRENCY }),
+    __param(0, Inject(LifecycleHooks)),
+    __param(1, Inject(KERNEL_LOGGER))
+], LifecycleHooksProcessor);
+export { LifecycleHooksProcessor };
+const LIFECYCLE_QUEUE_MODULE = QueueModule.registerQueue(LIFECYCLE_QUEUE);
+/** Lifecycle hook delivery: owing the jobs, and the queue the outbox adds them to, on every role. */
+let LifecycleHooksModule = class LifecycleHooksModule {
+};
+LifecycleHooksModule = __decorate([
+    Module({
+        imports: [ExtensionsModule, LIFECYCLE_QUEUE_MODULE],
+        providers: [LifecycleHooks],
+        exports: [LifecycleHooks, LIFECYCLE_QUEUE_MODULE],
+    })
+], LifecycleHooksModule);
+export { LifecycleHooksModule };
+/** The lifecycle queue's consumer; imported only by the worker role (`WorkerModule`). */
+let LifecycleHookWorkersModule = class LifecycleHookWorkersModule {
+};
+LifecycleHookWorkersModule = __decorate([
+    Module({
+        imports: [LifecycleHooksModule],
+        providers: [LifecycleHooksProcessor],
+        exports: [LifecycleHooksProcessor],
+    })
+], LifecycleHookWorkersModule);
+export { LifecycleHookWorkersModule };

package/dist/extensions/lifecycle.d.ts

@@ -7,6 +7,7 @@ import { ExtensionInstalls } from "./installs.js";
 import { PLUGINS_CHANGED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle-topics.js";
 import { PLUGINS_MIGRATED_TOPIC } from "./migrate-lock.js";
 import { ReplicaStatusStore } from "./sources.js";
+import { UsageSubscribers } from "./usage-subscribers.js";
 export { PLUGINS_CHANGED_TOPIC, PLUGINS_MIGRATED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, };
 /**
  * 每副本一个：把本副本的插件加载状态收敛到 PG 期望状态（C16）。
@@ -24,6 +25,8 @@ export declare class ExtensionLifecycle {
     private readonly installs;
     private readonly config;
     private readonly log;
+    /** "Does any plugin subscribe to usage.report": its cached answer is cleared on PLUGINS_CHANGED. */
+    private readonly usageSubscribers;
     private running;
     private queued;
     private unsubs;
@@ -32,7 +35,9 @@ export declare class ExtensionLifecycle {
     private stopped;
     constructor(host: ExtensionHost, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, status: ReplicaStatusStore, 
     /** Every install record's name (any desired state): prunes status rows this replica no longer knows. */
-    installs: ExtensionInstalls, config: KernelConfigService, log: KernelLogger);
+    installs: ExtensionInstalls, config: KernelConfigService, log: KernelLogger, 
+    /** "Does any plugin subscribe to usage.report": its cached answer is cleared on PLUGINS_CHANGED. */
+    usageSubscribers: Pick<UsageSubscribers, "invalidate">);
     /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
     start(): Promise<void>;
     /**

package/dist/extensions/lifecycle.js

@@ -17,6 +17,7 @@ import { ExtensionInstalls } from "./installs.js";
 import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC, PLUGINS_CHANGED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, } from "./lifecycle-topics.js";
 import { PLUGINS_MIGRATED_TOPIC } from "./migrate-lock.js";
 import { ReplicaStatusStore } from "./sources.js";
+import { UsageSubscribers } from "./usage-subscribers.js";
 export { PLUGINS_CHANGED_TOPIC, PLUGINS_MIGRATED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, };
 /** 心跳超过这么多个周期的行直接删除（副本早已退出；读的一方本来就不计入）。 */
 const PRUNE_RECONCILE_PERIODS = 10;
@@ -35,6 +36,7 @@ let ExtensionLifecycle = class ExtensionLifecycle {
     installs;
     config;
     log;
+    usageSubscribers;
     running;
     queued;
     unsubs = [];
@@ -43,13 +45,16 @@ let ExtensionLifecycle = class ExtensionLifecycle {
     stopped = false;
     constructor(host, bus, status, 
     /** Every install record's name (any desired state): prunes status rows this replica no longer knows. */
-    installs, config, log) {
+    installs, config, log, 
+    /** "Does any plugin subscribe to usage.report": its cached answer is cleared on PLUGINS_CHANGED. */
+    usageSubscribers) {
         this.host = host;
         this.bus = bus;
         this.status = status;
         this.installs = installs;
         this.config = config;
         this.log = log;
+        this.usageSubscribers = usageSubscribers;
     }
     /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
     async start() {
@@ -65,6 +70,7 @@ let ExtensionLifecycle = class ExtensionLifecycle {
         await on(PLUGINS_CHANGED_TOPIC, (p) => {
             // 安装 / 卸载改变了「部署已知」的插件名：路由闸门不等 TTL
             this.host.invalidateKnownNames();
+            this.usageSubscribers.invalidate();
             this.trigger(`changed:${pluginOf(p)}`);
         });
         await on(PLUGINS_RECONCILE_TOPIC, () => this.trigger("periodic"));
@@ -176,7 +182,8 @@ ExtensionLifecycle = __decorate([
     __param(2, Inject(ReplicaStatusStore)),
     __param(3, Inject(ExtensionInstalls)),
     __param(4, Inject(KernelConfigService)),
-    __param(5, Inject(KERNEL_LOGGER))
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(UsageSubscribers))
 ], ExtensionLifecycle);
 export { ExtensionLifecycle };
 const pluginOf = (p) => typeof p === "object" && p !== null && typeof p.plugin === "string"

package/dist/extensions/org-config.d.ts

@@ -110,6 +110,16 @@ export interface OrgExtensionPutOptions {
      */
     validateOnly?: boolean;
 }
+/**
+ * An org's stored config of a plugin no longer matches its org schema (e.g. after a plugin upgrade):
+ * a known state, not a read error. The message names the plugin, the org and the failing paths,
+ * never the values.
+ */
+export declare class OrgConfigInvalidError extends Error {
+    readonly plugin: string;
+    readonly orgId: string;
+    constructor(plugin: string, orgId: string, detail: string);
+}
 /**
  * Org-level extension config: enablement and the `config.org` config stored per org.
  * The non-secret part is stored in `capybara.extension_org_configs.config`; each secret field is
@@ -210,7 +220,9 @@ export declare class OrgExtensionConfigs {
      * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
      * 无记录 → undefined；插件无 `config.org` 或已停用（`enabled=false`，不校验、不读密钥）时 `config` 为 null。
      * 配置行与密钥在同一个 `REPEATABLE READ` 只读事务里读取。
-     * 已存配置不再满足 schema（如插件升级后）→ 抛 Error，信息含插件名、组织 ID 与出错路径（不含值）。
+     * A stored config that no longer matches the schema (e.g. after a plugin upgrade) throws
+     * {@link OrgConfigInvalidError} (plugin, org ID and the failing paths, no values); other errors are
+     * read errors.
      */
     get(orgId: string, plugin: string): Promise<{
         enabled: boolean;

package/dist/extensions/org-config.js

@@ -88,6 +88,21 @@ function secretPaths(schema) {
         .filter((f) => f.meta?.secret)
         .map((f) => f.path);
 }
+/**
+ * An org's stored config of a plugin no longer matches its org schema (e.g. after a plugin upgrade):
+ * a known state, not a read error. The message names the plugin, the org and the failing paths,
+ * never the values.
+ */
+export class OrgConfigInvalidError extends Error {
+    plugin;
+    orgId;
+    constructor(plugin, orgId, detail) {
+        super(`plugin ${plugin}: stored organization config for org ${orgId} is invalid: ${detail}`);
+        this.plugin = plugin;
+        this.orgId = orgId;
+        this.name = "OrgConfigInvalidError";
+    }
+}
 /**
  * Org-level extension config: enablement and the `config.org` config stored per org.
  * The non-secret part is stored in `capybara.extension_org_configs.config`; each secret field is
@@ -444,7 +459,9 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
      * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
      * 无记录 → undefined；插件无 `config.org` 或已停用（`enabled=false`，不校验、不读密钥）时 `config` 为 null。
      * 配置行与密钥在同一个 `REPEATABLE READ` 只读事务里读取。
-     * 已存配置不再满足 schema（如插件升级后）→ 抛 Error，信息含插件名、组织 ID 与出错路径（不含值）。
+     * A stored config that no longer matches the schema (e.g. after a plugin upgrade) throws
+     * {@link OrgConfigInvalidError} (plugin, org ID and the failing paths, no values); other errors are
+     * read errors.
      */
     async get(orgId, plugin) {
         const manifest = this.manifest(plugin);
@@ -488,7 +505,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             const detail = toIssues(r.error)
                 .map((i) => `${i.path || "<root>"}: ${i.message}`)
                 .join("; ");
-            throw new Error(`plugin ${plugin}: stored organization config for org ${orgId} is invalid: ${detail}`);
+            throw new OrgConfigInvalidError(plugin, orgId, detail);
         }
         return { enabled: true, config: r.data };
     }

package/dist/extensions/permission-view.d.ts

@@ -30,7 +30,7 @@ export interface PermissionGroup {
  * ({@link SENSITIVE_EXTENSION_POINTS}; the code is the extension point name without `@<major>`, with
  * `-` replaced by `_`).
  */
-export type SensitiveReason = "secrets" | "public_routes" | "tools" | "hooks" | "ui_embed" | "client_code" | "ui_component" | "channel" | "directory" | "identity_source" | "sandbox" | "object_store" | "migration_warnings";
+export type SensitiveReason = "secrets" | "public_routes" | "tools" | "hooks" | "ui_embed" | "client_code" | "ui_component" | "channel" | "directory" | "identity_source" | "sandbox" | "object_store" | "context" | "migration_warnings";
 /** 权限清单里的一项（分组里的一项，或 `added` 里的一个权限键）。 */
 export interface PermissionItem {
     value: string;
@@ -39,10 +39,14 @@ export interface PermissionItem {
     reason?: SensitiveReason;
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
- * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
- * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
+ * Sensitive capabilities (D10 + planned extensions, F-AI): `sandbox@2` runs arbitrary commands in
+ * the deployment, `object-store@1` holds every attachment and plugin package (D10); `channel@1`
+ * receives the org's IM conversations (Ruling A33), `directory@1` can add people to orgs (creating
+ * their accounts and identities), `identity-source@1` decides who can sign in as which account;
+ * `context@1` adds text to the model's context in conversations of orgs that enable it (memory
+ * plugin spec §6.1). A plugin providing any of them has its "provides" group marked sensitive and
+ * `sensitive` true in the admin plugin list, for the super admin to approve. Display only: the keys
+ * of the permission snapshot do not change.
  */
 export declare const SENSITIVE_EXTENSION_POINTS: readonly string[];
 /**

package/dist/extensions/permission-view.js

@@ -18,10 +18,14 @@ export function reviewHash(set, warnings = []) {
     return h.digest("hex").slice(0, 16);
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
- * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
- * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
+ * Sensitive capabilities (D10 + planned extensions, F-AI): `sandbox@2` runs arbitrary commands in
+ * the deployment, `object-store@1` holds every attachment and plugin package (D10); `channel@1`
+ * receives the org's IM conversations (Ruling A33), `directory@1` can add people to orgs (creating
+ * their accounts and identities), `identity-source@1` decides who can sign in as which account;
+ * `context@1` adds text to the model's context in conversations of orgs that enable it (memory
+ * plugin spec §6.1). A plugin providing any of them has its "provides" group marked sensitive and
+ * `sensitive` true in the admin plugin list, for the super admin to approve. Display only: the keys
+ * of the permission snapshot do not change.
  */
 export const SENSITIVE_EXTENSION_POINTS = [
     "channel@1",
@@ -29,6 +33,7 @@ export const SENSITIVE_EXTENSION_POINTS = [
     "identity-source@1",
     "sandbox@2",
     "object-store@1",
+    "context@1",
 ];
 /** The one item of the "client" group (client extensions spec §5.4). */
 const CLIENT_ITEM = "client code";

package/dist/extensions/point-defaults.d.ts

@@ -18,6 +18,16 @@ export type PointResolution<T> = {
     ok: false;
     reason: "none" | "ambiguous";
 };
+/**
+ * One provider of a multi-provider extension point for an org ({@link ExtensionPointDefaults.providersFor}),
+ * with its org config and its effective deployment config for the org, both to pass back to it.
+ */
+export interface PointProvider<T> {
+    extension: string;
+    impl: T;
+    orgConfig: unknown;
+    config: unknown;
+}
 /** One `org-default` extension point of an org (the admin view). */
 export interface OrgPointDefaultView {
     point: string;
@@ -50,6 +60,19 @@ export declare class ExtensionPointDefaults {
      * point has no `selection`.
      */
     resolve<T>(orgId: string, point: string): Promise<PointResolution<T>>;
+    /**
+     * Every provider of `point` (the name without the major, e.g. `context`) that could serve
+     * `orgId` now, in extension-name order: the same candidates {@link resolve} chooses from (loaded
+     * here, enabled in the org, valid org and effective config, `configured()` not false), for
+     * points whose every enabled provider is used (no `selection`). `failed`: the providers enabled
+     * in the org whose status could not be read (reading a config or `configured()` threw, e.g. a
+     * transient database error); they are neither serving nor known to be off. An invalid stored
+     * org config ({@link OrgConfigInvalidError}) is not a read error: that provider is off.
+     */
+    providersFor<T>(orgId: string, point: string): Promise<{
+        providers: PointProvider<T>[];
+        failed: Set<string>;
+    }>;
     /** Every `org-default` point with its candidates, stored default and effective provider. */
     list(orgId: string): Promise<OrgPointDefaultView[]>;
     /** Whether each `org-default` point has a provider for the org now (no extension names). */
@@ -65,7 +88,11 @@ export declare class ExtensionPointDefaults {
     setDefault(orgId: string, point: string, extension: string, actorId: string, 
     /** Merged into the audit detail (a write made through the Platform tool). */
     auditDetail?: Record<string, unknown>): Promise<void>;
-    /** The candidates of `point` in `orgId`, by extension name. */
+    /**
+     * The candidates of `point` in `orgId`, by extension name, and the enabled providers whose status
+     * could not be read (a read or `configured()` threw: excluded, logged). A provider whose stored
+     * org config or effective config is invalid is excluded but not `failed`: it is known to be off.
+     */
     private candidates;
     private choose;
     /** The org's stored defaults, point → extension. */

package/dist/extensions/point-defaults.js

@@ -17,7 +17,7 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { EffectiveConfigs } from "./effective-config.js";
 import { enabledExtensionsQuery, isExtensionEnabled } from "./enabled.js";
-import { OrgExtensionConfigs } from "./org-config.js";
+import { OrgConfigInvalidError, OrgExtensionConfigs } from "./org-config.js";
 import { ExtensionRegistry } from "./registry.js";
 /** The extension points whose provider each org chooses (`selection: "org-default"`). */
 function selectionPoints() {
@@ -58,7 +58,7 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
         if (!hasSelection(point)) {
             throw new Error(`extension point ${point} has no org-default selection`);
         }
-        const candidates = await this.candidates(orgId, point);
+        const { candidates } = await this.candidates(orgId, point);
         const chosen = await this.choose(orgId, point, candidates);
         if (!chosen.ok)
             return chosen;
@@ -71,12 +71,33 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
             config: c.config,
         };
     }
+    /**
+     * Every provider of `point` (the name without the major, e.g. `context`) that could serve
+     * `orgId` now, in extension-name order: the same candidates {@link resolve} chooses from (loaded
+     * here, enabled in the org, valid org and effective config, `configured()` not false), for
+     * points whose every enabled provider is used (no `selection`). `failed`: the providers enabled
+     * in the org whose status could not be read (reading a config or `configured()` threw, e.g. a
+     * transient database error); they are neither serving nor known to be off. An invalid stored
+     * org config ({@link OrgConfigInvalidError}) is not a read error: that provider is off.
+     */
+    async providersFor(orgId, point) {
+        const { candidates, failed } = await this.candidates(orgId, point);
+        return {
+            providers: candidates.map((c) => ({
+                extension: c.extension,
+                impl: c.impl,
+                orgConfig: c.orgConfig,
+                config: c.config,
+            })),
+            failed,
+        };
+    }
     /** Every `org-default` point with its candidates, stored default and effective provider. */
     async list(orgId) {
         const stored = await this.storedDefaults(orgId);
         const out = [];
         for (const point of selectionPoints()) {
-            const candidates = await this.candidates(orgId, point);
+            const { candidates } = await this.candidates(orgId, point);
             const chosen = pick(candidates, stored.get(point));
             out.push({
                 point,
@@ -128,7 +149,11 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
             detail: { point, extension, ...auditDetail },
         });
     }
-    /** The candidates of `point` in `orgId`, by extension name. */
+    /**
+     * The candidates of `point` in `orgId`, by extension name, and the enabled providers whose status
+     * could not be read (a read or `configured()` threw: excluded, logged). A provider whose stored
+     * org config or effective config is invalid is excluded but not `failed`: it is known to be off.
+     */
     async candidates(orgId, point) {
         const db = this.kdb.db;
         const enabled = new Set((await db
@@ -141,18 +166,21 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
                 providers.set(e.plugin, e.impl);
         }
         const out = [];
+        const failed = new Set();
         for (const [extension, impl] of providers) {
             let cfg;
             try {
                 cfg = await this.orgConfigs.get(orgId, extension);
             }
             catch (err) {
-                this.log.warn("org default provider: provider excluded, its org config is invalid", {
-                    orgId,
-                    point,
-                    extension,
-                    err,
-                });
+                // a stored org config that no longer validates is a known state: the provider is off
+                // (as for an invalid effective config below); only a read that failed is `failed`
+                const invalid = err instanceof OrgConfigInvalidError;
+                this.log.warn(invalid
+                    ? "extension point provider excluded, its stored org config is invalid"
+                    : "extension point provider excluded, cannot read its org config", { orgId, point, extension, err });
+                if (!invalid)
+                    failed.add(extension);
                 continue;
             }
             if (!cfg?.enabled)
@@ -163,12 +191,13 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
                 effective = await this.effective.get(orgId, extension);
             }
             catch (err) {
-                this.log.warn("org default provider: provider excluded, cannot read its effective config", {
+                this.log.warn("extension point provider excluded, cannot read its effective config", {
                     orgId,
                     point,
                     extension,
                     err,
                 });
+                failed.add(extension);
                 continue;
             }
             if (!effective.ok)
@@ -181,12 +210,13 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
                     ok = configured.call(impl, cfg.config, effective.config) !== false;
                 }
                 catch (err) {
-                    this.log.warn("org default provider: provider excluded, configured() threw", {
+                    this.log.warn("extension point provider excluded, configured() threw", {
                         orgId,
                         point,
                         extension,
                         err,
                     });
+                    failed.add(extension);
                     continue;
                 }
                 if (!ok)
@@ -194,7 +224,8 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
             }
             out.push({ extension, impl, orgConfig: cfg.config, config: effective.config });
         }
-        return out.sort((a, b) => (a.extension < b.extension ? -1 : a.extension > b.extension ? 1 : 0));
+        out.sort((a, b) => (a.extension < b.extension ? -1 : a.extension > b.extension ? 1 : 0));
+        return { candidates: out, failed };
     }
     async choose(orgId, point, candidates) {
         if (candidates.length < 2)