@capybara-hq/kernel 0.1.0-rc.14 → 0.1.0-rc.15

package/dist/extensions/host.js

@@ -1176,15 +1176,24 @@ let ExtensionHost = class ExtensionHost {
     /**
      * 写本副本的加载状态；失败只记 warn（状态是给后台看的，不影响加载）。这一行的版本没加载成（failed / pending）
      * 而本副本仍有别的版本在跑时，记下那个版本（`servingVersion`，后台同时显示「新版失败、旧版仍在服务」）。
+     * `servingSha256` is the package this replica actually serves for the plugin (client code follows
+     * it, client extensions spec §9.3): the row's own package when loaded; for a failed / pending row
+     * the package of the instance still running here (an older one, or the row's own package when it
+     * stays loaded, e.g. beside a provider conflict), else null.
      */
     async writeStatus(s) {
-        if (s.servingVersion === undefined && (s.state === "failed" || s.state === "pending")) {
-            const cur = this.registry.current(s.plugin);
-            s = {
-                ...s,
-                servingVersion: cur && (cur.sha256 !== s.sha256 || cur.version !== s.version) ? cur.version : null,
-            };
-        }
+        const waiting = s.state === "failed" || s.state === "pending";
+        const cur = waiting ? this.registry.current(s.plugin) : undefined;
+        const other = cur && (cur.sha256 !== s.sha256 || cur.version !== s.version) ? cur : null;
+        s = {
+            ...s,
+            ...(waiting && s.servingVersion === undefined && { servingVersion: other?.version ?? null }),
+            servingSha256: s.servingSha256 !== undefined
+                ? s.servingSha256
+                : s.state === "loaded"
+                    ? s.sha256
+                    : (cur?.sha256 ?? null),
+        };
         if (s.source === "install") {
             if (s.state === "unloaded")
                 this.installRows.delete(s.plugin);
@@ -2103,8 +2112,10 @@ let ExtensionHost = class ExtensionHost {
      */
     uiContributions() {
         return this.registry.all().flatMap((i) => i.ui.map(({ contribution: c, slot, after }) => {
-            const render = c.kind === "view" ? i.uiViews.get(c.id) : undefined;
-            const action = c.kind === "view" ? i.uiActions.get(c.id) : undefined;
+            // a view's, or a component's server view (client extensions spec §5.2); embeds have none
+            const served = c.kind === "view" || c.kind === "component";
+            const render = served ? i.uiViews.get(c.id) : undefined;
+            const action = served ? i.uiActions.get(c.id) : undefined;
             return {
                 plugin: i.name,
                 contribution: c,

package/dist/extensions/package.d.ts

@@ -29,10 +29,11 @@ export { HOST_ZOD_VERSION };
 /** Unpack limits: `maxBytes` is `packages.maxBytes`; the rest default to {@link EXTENSION_PACKAGE_LIMITS}. */
 export type ExtensionPackageLimits = PackageTgzLimits;
 /**
- * Codes of {@link ExtensionPackageError}: an invalid package, a tgz in the pre-0.1.0 format, or a
- * plugin without an extension (nothing to install on the deployment).
+ * Codes of {@link ExtensionPackageError}: an invalid package, a tgz in the pre-0.1.0 format, a
+ * plugin without an extension (nothing to install on the deployment), or client code the
+ * extension manifest does not declare.
  */
-export type ExtensionPackageErrorCode = "extension.package_invalid" | "extension.legacy_format" | "extension.no_extension";
+export type ExtensionPackageErrorCode = "extension.package_invalid" | "extension.legacy_format" | "extension.no_extension" | "client.undeclared";
 /** The extension package is invalid; `issues` lists the problems (English, shown to the admin). */
 export declare class ExtensionPackageError extends Error {
     readonly code: ExtensionPackageErrorCode;

package/dist/extensions/package.js

@@ -111,7 +111,11 @@ function checkModuleGraph(entry, byPath) {
     return issues;
 }
 /** Maps an error of `readPluginPackage` to the extension package error. */
-const fromPluginPackageError = (e) => new ExtensionPackageError(e.issues, e.code === "catalog.legacy_format" ? "extension.legacy_format" : "extension.package_invalid");
+const fromPluginPackageError = (e) => new ExtensionPackageError(e.issues, e.code === "catalog.legacy_format"
+    ? "extension.legacy_format"
+    : e.code === "client.undeclared"
+        ? "client.undeclared"
+        : "extension.package_invalid");
 /**
  * Reads and validates an extension package without running any code from it: a plugin tgz
  * (`readPluginPackage`) with an `extension` section, whose entry's module graph passes the import

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

@@ -42,12 +42,20 @@ export interface PermissionSet {
         }[];
         network: string[];
         /**
-         * 界面贡献（`permissions.ui`）：`views` 记入快照但不卡加载（升级时自动补进快照）；
-         * `embeds` 与其他权限一样卡加载。旧快照没有这一项（按空处理）。
+         * Client code (`permissions.client`, client extensions spec §5.4): the plugin ships a browser
+         * bundle that runs with full trust in members' browsers. Sensitive and blocking. Older snapshots
+         * lack it (read as false).
+         */
+        client: boolean;
+        /**
+         * UI contributions (`permissions.ui`): `views` are recorded in the snapshot without blocking the
+         * load (added to the snapshot automatically on upgrade); `embeds` and `components` block the
+         * load like any other permission. Older snapshots lack `ui` or `components` (read as empty).
          */
         ui: {
             views: string[];
             embeds: string[];
+            components: string[];
         };
         /**
          * Setup check ids (`permissions.setupChecks`, setup guides v2 §10.2): recorded and shown at
@@ -100,7 +108,8 @@ export declare function buildPermissionSet(input: {
 }): PermissionSet;
 /**
  * 权限集合的稳定字符串键（排序），如 `provides:channel@1`、`config.org.secret:apiKey`、`table:todos`、
- * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`。
+ * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`,
+ * `permissions.client`, `ui.component:hud`.
  * 容忍旧快照缺字段（按空处理），快照格式演进时不会抛错。
  */
 export declare function permissionKeys(set: PermissionSet): string[];
@@ -109,6 +118,13 @@ export declare function permissionKeys(set: PermissionSet): string[];
  * Lower-case letters and dots only, as catalog permission keys require (`PERMISSION_KEY_RE`).
  */
 export declare const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
+/**
+ * Permission key of client code (`permissions.client`): sensitive and blocking. The key, not the
+ * bundle's bytes, is reviewed: an upgrade that only changes the bundle adds no key.
+ */
+export declare const CLIENT_KEY = "permissions.client";
+/** Key prefix of a client component (`ui.component:<id>`): sensitive and blocking. */
+export declare const UI_COMPONENT_KEY_PREFIX = "ui.component:";
 /** 渲染 schema 视图的权限键前缀：记入快照但不卡加载（见 {@link blockingKeys}）。 */
 export declare const UI_VIEW_KEY_PREFIX = "ui.view:";
 /**

package/dist/extensions/permission-set.js

@@ -107,7 +107,12 @@ export function buildPermissionSet(input) {
                 .map((m) => ({ purpose: m.purpose, kind: m.kind }))
                 .sort((a, b) => cmp(a.purpose, b.purpose)),
             network: sortedUnique(p.network),
-            ui: { views: sortedUnique(p.ui?.views), embeds: sortedUnique(p.ui?.embeds) },
+            client: p.client === true,
+            ui: {
+                views: sortedUnique(p.ui?.views),
+                embeds: sortedUnique(p.ui?.embeds),
+                components: sortedUnique(p.ui?.components),
+            },
             // only when declared: sets (and snapshots) of plugins without setup checks stay as they were
             ...(p.setupChecks && p.setupChecks.length > 0
                 ? { setupChecks: sortedUnique(p.setupChecks) }
@@ -118,7 +123,8 @@ export function buildPermissionSet(input) {
 }
 /**
  * 权限集合的稳定字符串键（排序），如 `provides:channel@1`、`config.org.secret:apiKey`、`table:todos`、
- * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`。
+ * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`,
+ * `permissions.client`, `ui.component:hud`.
  * 容忍旧快照缺字段（按空处理），快照格式演进时不会抛错。
  */
 export function permissionKeys(set) {
@@ -155,10 +161,14 @@ export function permissionKeys(set) {
         keys.push(`permissions.models:${m.purpose} (${m.kind})`);
     for (const d of p.network ?? [])
         keys.push(`permissions.network:${d}`);
+    if (p.client)
+        keys.push(CLIENT_KEY);
     for (const v of p.ui?.views ?? [])
         keys.push(`${UI_VIEW_KEY_PREFIX}${v}`);
     for (const e of p.ui?.embeds ?? [])
         keys.push(`ui.embed:${e}`);
+    for (const c of p.ui?.components ?? [])
+        keys.push(`${UI_COMPONENT_KEY_PREFIX}${c}`);
     for (const c of p.setupChecks ?? [])
         keys.push(`${SETUP_CHECK_KEY_PREFIX}${c}`);
     if (s.warningsDigest)
@@ -170,6 +180,13 @@ export function permissionKeys(set) {
  * Lower-case letters and dots only, as catalog permission keys require (`PERMISSION_KEY_RE`).
  */
 export const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
+/**
+ * Permission key of client code (`permissions.client`): sensitive and blocking. The key, not the
+ * bundle's bytes, is reviewed: an upgrade that only changes the bundle adds no key.
+ */
+export const CLIENT_KEY = "permissions.client";
+/** Key prefix of a client component (`ui.component:<id>`): sensitive and blocking. */
+export const UI_COMPONENT_KEY_PREFIX = "ui.component:";
 /** 渲染 schema 视图的权限键前缀：记入快照但不卡加载（见 {@link blockingKeys}）。 */
 export const UI_VIEW_KEY_PREFIX = "ui.view:";
 /**

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

@@ -12,11 +12,11 @@ import type { ExtensionSource } from "./sources.js";
 export declare function reviewHash(set: PermissionSet, warnings?: readonly PackageWarning[]): string;
 /** 权限清单展示用的一组：按类别分组，`sensitive` 标出需要管理员特别留意的类别。 */
 export interface PermissionGroup {
-    category: "provides" | "requires" | "optional" | "config" | "tables" | "secrets" | "storage" | "http" | "publicRoutes" | "tools" | "hooks" | "models" | "network" | "ui";
+    category: "provides" | "requires" | "optional" | "config" | "tables" | "secrets" | "storage" | "http" | "publicRoutes" | "tools" | "hooks" | "models" | "network" | "ui" | "client";
     /**
-     * Sensitive category: secrets, public routes, tools, hooks; also the "provides" group when it holds
-     * one of {@link SENSITIVE_EXTENSION_POINTS}, and the "UI" group when it holds an embedded app
-     * (embed: the extension's own page in an iframe).
+     * Sensitive category: secrets, public routes, tools, hooks, client code; also the "provides" group
+     * when it holds one of {@link SENSITIVE_EXTENSION_POINTS}, and the "UI" group when it holds an
+     * embedded app (embed: the extension's own page in an iframe) or a client component.
      */
     sensitive: boolean;
     items: string[];
@@ -25,10 +25,12 @@ export interface PermissionGroup {
 }
 /**
  * Sensitive reason codes (the UI translates them by code): secrets, public routes, tools, hooks,
- * embedded apps, and sensitive extension points ({@link SENSITIVE_EXTENSION_POINTS}; the code is the
- * extension point name without `@<major>`, with `-` replaced by `_`).
+ * embedded apps, client code and client components (client extensions spec §5.4: code that runs with
+ * full trust in members' browsers), and sensitive extension points
+ * ({@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" | "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" | "migration_warnings";
 /** 权限清单里的一项（分组里的一项，或 `added` 里的一个权限键）。 */
 export interface PermissionItem {
     value: string;
@@ -151,6 +153,35 @@ export interface AdminExtensionView {
         ref: string;
         reason: UiDropReason;
     }[];
+    /**
+     * The client build that runs (client extensions spec §9.1, §9.3, §10.4): the one a live replica
+     * serves (the install's own package when it runs, else the older one still served beside an
+     * upgrade awaiting approval or failed), or the install record package's build when no replica
+     * serves one; its id (the package sha256), every file with its size, and the client API
+     * version; null when that package has no client code (or the view is degraded).
+     */
+    client: {
+        build: string;
+        files: {
+            path: string;
+            bytes: number;
+        }[];
+        apiVersion: number;
+    } | null;
+    /**
+     * Crash and load reports of that build, newest first, at most 50: `orgId` is null for admin
+     * pages and may name an org deleted since (rows stay until the 30-day prune). Empty without a
+     * client build.
+     */
+    clientReports: {
+        orgId: string | null;
+        contribution: string | null;
+        kind: string;
+        count: number;
+        firstAt: string;
+        lastAt: string;
+        lastMessage: string;
+    }[];
     /**
      * Only with status `conflict`: the single-provider extension point and the other extensions that
      * provide it (they keep this one from loading; disabling them loads it, no restart).

package/dist/extensions/permission-view.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { pluginSchemaName } from "../ctx/create-ctx.js";
 import { isDestructiveSql, splitSqlStatements } from "../db/sql-statements.js";
-import { permissionKeys, WARNINGS_KEY_PREFIX } from "./permission-set.js";
+import { CLIENT_KEY, permissionKeys, UI_COMPONENT_KEY_PREFIX, WARNINGS_KEY_PREFIX, } from "./permission-set.js";
 /**
  * Review digest: the first 16 hex digits of `sha256(permissionKeys(set).join("\n"))`; with migration
  * warnings their digest (kind, file, line and statement) is folded in, without warnings it equals the
@@ -30,23 +30,28 @@ export const SENSITIVE_EXTENSION_POINTS = [
     "sandbox@2",
     "object-store@1",
 ];
+/** The one item of the "client" group (client extensions spec §5.4). */
+const CLIENT_ITEM = "client code";
 /** 总是敏感的类别。 */
 const ALWAYS_SENSITIVE = new Set([
     "secrets",
     "publicRoutes",
     "tools",
     "hooks",
+    "client",
 ]);
 const CATEGORY_REASON = {
     secrets: "secrets",
     publicRoutes: "public_routes",
     tools: "tools",
     hooks: "hooks",
+    client: "client_code",
 };
 /**
  * Why an item in a category is sensitive (undefined when it is not; shared by the grouped list, the
- * per-item `added` and the CLI markers): secrets, public routes, tools and hooks are always
- * sensitive; {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`) in "UI".
+ * per-item `added` and the CLI markers): secrets, public routes, tools, hooks and client code are
+ * always sensitive; {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`)
+ * and client components (`component:<id>`) in "UI".
  */
 function itemReason(category, item) {
     // storage 不算敏感：ctx.storage 的键由内核加前缀 `plugins/<插件>/<orgId>/`，插件只能读写自己的前缀
@@ -55,8 +60,13 @@ function itemReason(category, item) {
             ? item.split("@")[0].replaceAll("-", "_")
             : undefined;
     }
-    if (category === "ui")
-        return item.startsWith("embed:") ? "ui_embed" : undefined;
+    if (category === "ui") {
+        if (item.startsWith("embed:"))
+            return "ui_embed";
+        if (item.startsWith("component:"))
+            return "ui_component";
+        return undefined;
+    }
     return ALWAYS_SENSITIVE.has(category) ? CATEGORY_REASON[category] : undefined;
 }
 const itemOf = (category, value) => {
@@ -68,6 +78,8 @@ function keyItem(key) {
     const after = (prefix) => (key.startsWith(prefix) ? key.slice(prefix.length) : null);
     if (key === "permissions.secrets")
         return { category: "secrets", item: "secret store" };
+    if (key === CLIENT_KEY)
+        return { category: "client", item: CLIENT_ITEM };
     if (/^config\.(deployment|org)\.secret:/.test(key))
         return { category: "secrets", item: key.slice(key.indexOf(":") + 1) };
     const table = [
@@ -77,6 +89,7 @@ function keyItem(key) {
         ["permissions.hooks:", "hooks", ""],
         ["permissions.hooks.policy:", "hooks", "policy:"],
         ["ui.embed:", "ui", "embed:"],
+        [UI_COMPONENT_KEY_PREFIX, "ui", "component:"],
         ["ui.view:", "ui", "view:"],
     ];
     for (const [prefix, category, itemPrefix] of table) {
@@ -113,8 +126,9 @@ export function permissionKeyItems(keys) {
 /** 把权限集合整理成分组清单（固定顺序，空组省略）。纯函数。 */
 export function permissionGroups(set) {
     const p = set.permissions;
-    // 旧快照没有 ui（按空处理）
-    const ui = p.ui ?? { views: [], embeds: [] };
+    // older snapshots lack `ui`, `ui.components` and `client` (read as empty / false)
+    const ui = p.ui ?? { views: [], embeds: [], components: [] };
+    const components = ui.components ?? [];
     const secretFields = [...set.config.deployment, ...set.config.org]
         .filter((f) => f.secret)
         .map((f) => f.path || "<root>");
@@ -148,8 +162,13 @@ export function permissionGroups(set) {
         { category: "network", items: p.network },
         {
             category: "ui",
-            items: [...ui.views.map((v) => `view:${v}`), ...ui.embeds.map((e) => `embed:${e}`)],
+            items: [
+                ...ui.views.map((v) => `view:${v}`),
+                ...ui.embeds.map((e) => `embed:${e}`),
+                ...components.map((c) => `component:${c}`),
+            ],
         },
+        { category: "client", items: p.client === true ? [CLIENT_ITEM] : [] },
     ];
     return groups
         .filter((g) => g.items.length > 0)

package/dist/extensions/sources.d.ts

@@ -36,6 +36,12 @@ export interface ExtensionLoadStatus {
      * 省略视同 null。
      */
     servingVersion?: string | null;
+    /**
+     * The package sha256 this replica serves for the plugin: the row's own `sha256` when `loaded`,
+     * the older package still running beside a failed / pending version, null when none runs.
+     * Omitted counts as null.
+     */
+    servingSha256?: string | null;
 }
 /** This replica's extension load status (PG `extension_replica_status`; each replica writes only its own rows). */
 export declare class ReplicaStatusStore {

package/dist/extensions/sources.js

@@ -55,6 +55,7 @@ let ReplicaStatusStore = class ReplicaStatusStore {
             reason: s.reason,
             detail: s.detail === null ? null : this.cleanDetail(s.detail),
             serving_version: s.servingVersion ?? null,
+            serving_sha256: s.servingSha256 ?? null,
             http_replica_id: this.httpReplicaId ?? null,
             heartbeat_at: sql `now()`,
         };
@@ -69,6 +70,7 @@ let ReplicaStatusStore = class ReplicaStatusStore {
             reason: values.reason,
             detail: values.detail,
             serving_version: values.serving_version,
+            serving_sha256: values.serving_sha256,
             http_replica_id: values.http_replica_id,
             heartbeat_at: values.heartbeat_at,
         }))

package/dist/extensions/state.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { ClientModule } from "../client/client.module.js";
 import { SuperAdminLockModule } from "../identity/super-admin.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { StorageModule } from "../storage/storage.module.js";
@@ -24,7 +25,14 @@ let ExtensionStateModule = class ExtensionStateModule {
 };
 ExtensionStateModule = __decorate([
     Module({
-        imports: [ExtensionRegistryModule, SuperAdminLockModule, OrgLockModule, StorageModule],
+        imports: [
+            ExtensionRegistryModule,
+            SuperAdminLockModule,
+            OrgLockModule,
+            StorageModule,
+            // a package with client code stores its client build (`ExtensionBlobs`)
+            ClientModule,
+        ],
         providers: [ExtensionApprovals, ExtensionBlobs, ExtensionInstalls, EffectiveConfigs],
         exports: [
             ExtensionRegistryModule,

package/dist/http/api.module.js

@@ -19,6 +19,7 @@ import { AgentSaveAsTemplateController, AgentTemplatesController, } from "../age
 import { BackgroundController } from "../background/background.controller.js";
 import { BackgroundModule } from "../background/background.module.js";
 import { AdminCatalogController } from "../catalog/admin-catalog.controller.js";
+import { AppearanceModule } from "../catalog/appearance.service.js";
 import { CatalogModule } from "../catalog/catalog.module.js";
 import { AdminComponentsController, OrgComponentsController, } from "../catalog/component-scope.controller.js";
 import { MarketplacesController, OrgMarketplacesController, } from "../catalog/marketplaces.controller.js";
@@ -27,6 +28,9 @@ import { OrgExtensionConfigsController, OrgExtensionOverridesController, OrgExte
 import { OrgOwnedPluginsController, OrgPluginUploadsController, } from "../catalog/org-plugin-uploads.controller.js";
 import { ChannelsModule } from "../channels/channels.module.js";
 import { ChannelConnectionsController } from "../channels/connections.controller.js";
+import { AdminClientController, OrgClientController } from "../client/client.controller.js";
+import { ClientModule } from "../client/client.module.js";
+import { ClientDeliveryController } from "../client/client-delivery.controller.js";
 import { AttachmentsController } from "../conversations/attachments.controller.js";
 import { ConversationsController } from "../conversations/conversations.controller.js";
 import { ConversationsModule } from "../conversations/conversations.module.js";
@@ -151,6 +155,9 @@ const CONTROLLERS = [
     ThemeDeliveryController,
     PlatformThemeController,
     DeviceAuthController,
+    ClientDeliveryController,
+    OrgClientController,
+    AdminClientController,
 ];
 /**
  * The api role (nest kernel spec §2): the kernel API (`/api/v1/*`), imported by `KernelModule` only
@@ -171,6 +178,8 @@ ApiModule = __decorate([
             AdminModule,
             ExtensionsModule,
             CatalogModule,
+            // a plugin's suggested appearance (its own module: it writes through the org settings)
+            AppearanceModule,
             ToolsModule,
             AgentsModule,
             ConversationsModule,
@@ -184,6 +193,7 @@ ApiModule = __decorate([
             UiModule,
             InboxModule,
             ThemesModule,
+            ClientModule,
             SetupModule,
         ],
         controllers: CONTROLLERS,

package/dist/identity/settings.d.ts

@@ -44,6 +44,31 @@ export declare const UiThemeSetting: z.ZodObject<{
     id: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type UiTheme = z.infer<typeof UiThemeSetting>;
+/** The deployment setting key of the client code kill switch (client extensions spec §10.2). */
+export declare const CLIENT_EXTENSIONS_SETTING = "clientExtensions";
+/** The plugins listed in `clientExtensions.disabled`: at most this many. */
+export declare const CLIENT_DISABLED_MAX = 200;
+/**
+ * The client code kill switch (client extensions spec §10.2): `enabled: false` stops every plugin's
+ * client code (the shell reads list nothing, delivery is 404); `disabled` names the plugins whose
+ * client code alone is stopped while their server side keeps running. Every reader goes through
+ * {@link readClientExtensions} or {@link SettingsService.get}.
+ */
+export declare const ClientExtensionsSetting: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    disabled: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ClientExtensionsKillSwitch = z.infer<typeof ClientExtensionsSetting>;
+/** The kill switch's default (and what a missing or invalid stored value reads as): everything on. */
+export declare const clientExtensionsDefault: () => ClientExtensionsKillSwitch;
+/**
+ * Parses a stored `clientExtensions` value (the `deployment_settings` row's `value`, undefined when
+ * the row is missing): the default when missing; when invalid the default too, with a warning naming
+ * the key (a kill switch that fails open is worth a log line, as {@link SettingsService.get} logs
+ * every other invalid key). The one parser of the setting: the settings service and every access
+ * check read through it.
+ */
+export declare function parseClientExtensions(value: unknown, log?: Pick<KernelLogger, "warn">): ClientExtensionsKillSwitch;
 export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
     orgCreation: z.ZodDefault<z.ZodEnum<{
         anyone: "anyone";
@@ -73,19 +98,11 @@ export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
     uiTheme: z.ZodDefault<z.ZodObject<{
         id: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
-    uiArrangement: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
-        "agent.detail.section": "agent.detail.section";
-        "conversation.panel": "conversation.panel";
-        "conversation.properties.section": "conversation.properties.section";
-        "conversation.tool-result.card": "conversation.tool-result.card";
-        "file.preview": "file.preview";
-        "org.page": "org.page";
-        "org.settings.section": "org.settings.section";
-        "platform.page": "platform.page";
-    }> & z.core.$partial, z.ZodObject<{
-        hidden: z.ZodArray<z.ZodString>;
-        order: z.ZodArray<z.ZodString>;
-    }, z.core.$strict>>>;
+    uiArrangement: z.ZodDefault<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown>>>;
+    clientExtensions: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        disabled: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type DeploymentSettings = z.infer<typeof DEPLOYMENT_SETTINGS>;
 /**
@@ -125,19 +142,11 @@ export declare const DEPLOYMENT_SETTINGS_PATCH: z.ZodObject<{
     uiTheme: z.ZodOptional<z.ZodObject<{
         id: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
-    uiArrangement: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        "agent.detail.section": "agent.detail.section";
-        "conversation.panel": "conversation.panel";
-        "conversation.properties.section": "conversation.properties.section";
-        "conversation.tool-result.card": "conversation.tool-result.card";
-        "file.preview": "file.preview";
-        "org.page": "org.page";
-        "org.settings.section": "org.settings.section";
-        "platform.page": "platform.page";
-    }> & z.core.$partial, z.ZodNullable<z.ZodObject<{
-        hidden: z.ZodArray<z.ZodString>;
-        order: z.ZodArray<z.ZodString>;
-    }, z.core.$strict>>>>;
+    uiArrangement: z.ZodOptional<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown>>>;
+    clientExtensions: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        disabled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type DeploymentSettingsPatch = z.infer<typeof DEPLOYMENT_SETTINGS_PATCH>;
 /**
@@ -177,6 +186,12 @@ export declare function readUiTheme(db: KernelSchemaDb, opts?: {
  * stored value reads as `{}` (the same fallback {@link SettingsService.get} uses).
  */
 export declare function readUiArrangement(db: KernelSchemaDb): Promise<UiArrangement>;
+/**
+ * The client code kill switch, read live from PG on every request (in the caller's transaction when
+ * there is one; never cached: every replica sees a change at once), through
+ * {@link parseClientExtensions} (missing or invalid -> everything on; invalid also warns on `log`).
+ */
+export declare function readClientExtensions(db: KernelSchemaDb, log?: Pick<KernelLogger, "warn">): Promise<ClientExtensionsKillSwitch>;
 /** Deployment settings: one row per key, defaults for missing keys. */
 export declare class SettingsService {
     private readonly db;