@capybara-hq/kernel 0.1.0-rc.10 → 0.1.0-rc.12

package/dist/db/kernel-schema.d.ts

@@ -1,4 +1,4 @@
-import type { FileSystemHandle, SkillInvocation } from "@capybara-hq/plugin-sdk";
+import type { FileSystemHandle, ParsedTheme, SkillInvocation } from "@capybara-hq/plugin-sdk";
 import type { ColumnType, Generated, Kysely } from "kysely";
 /** 带默认值的时间戳列：插入可省略，读出为 Date。 */
 type Ts = ColumnType<Date, Date | string | undefined, Date | string>;
@@ -20,6 +20,8 @@ export interface AccountsTable {
     time_zone: ColumnType<string | null, string | null | undefined, string | null>;
     /** 0090: the account must set its own password first (a generated initial password). */
     must_change_password: Generated<boolean>;
+    /** 0093: the person's theme id across all their orgs; null follows the org (themes spec §7). */
+    theme: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /**
  * 0090: a generated initial password sealed for the person who approved the account's creation,
@@ -418,6 +420,18 @@ export interface ConnectorsTable {
     /** 0081: the platform connector template this connector was made from (null = none). */
     platform_template_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
+/**
+ * 0104: a member's own policy for one tool of a personal-credential connector, for calls made with
+ * their own connection (maintainer decision 2026-11-09).
+ */
+export interface ConnectorToolAccountPoliciesTable {
+    org_id: string;
+    connector_id: string;
+    account_id: string;
+    tool_name: string;
+    policy: "allow" | "ask" | "deny";
+    updated_at: Ts;
+}
 /** 0010_tools.sql（0033 由 `app_tools` 改名）：连接器暴露的工具。 */
 export interface ConnectorToolsTable {
     connector_id: string;
@@ -1140,6 +1154,7 @@ export interface KernelDatabase {
     lg_checkpoint_writes: LgCheckpointWritesTable;
     connectors: ConnectorsTable;
     connector_tools: ConnectorToolsTable;
+    connector_tool_account_policies: ConnectorToolAccountPoliciesTable;
     tool_grants: ToolGrantsTable;
     conversation_tool_grants: ConversationToolGrantsTable;
     approvals: ApprovalsTable;
@@ -1195,6 +1210,8 @@ export interface KernelDatabase {
     platform_agent_templates: PlatformAgentTemplatesTable;
     platform_agent_template_versions: PlatformAgentTemplateVersionsTable;
     platform_connector_templates: PlatformConnectorTemplatesTable;
+    platform_themes: PlatformThemesTable;
+    platform_theme_versions: PlatformThemeVersionsTable;
     component_scope_orgs: ComponentScopeOrgsTable;
     component_org_switches: ComponentOrgSwitchesTable;
     plugin_installs: PluginInstallsTable;
@@ -1319,7 +1336,7 @@ export interface CatalogItemOrgSwitchesTable {
 }
 type ScopeMode = "follow" | "own";
 type ComponentScope = "all" | "optional" | "named";
-type ComponentKind = "skill" | "agent_template" | "connector_template";
+type ComponentKind = "skill" | "agent_template" | "connector_template" | "theme";
 type Dflt<T> = ColumnType<T, T | undefined, T>;
 type NullableDflt<T> = ColumnType<T | null, T | null | undefined, T | null>;
 /** 0081: the scope columns every platform component carries (ruling C2). */
@@ -1409,6 +1426,39 @@ export interface PlatformConnectorTemplatesTable extends PlatformScopeColumns {
     updated_at: Ts;
     deleted_at: TsNullable;
 }
+/** 0093: a theme (themes spec §6); every theme comes from a plugin, owned by the platform or an org. */
+export interface PlatformThemesTable extends PlatformScopeColumns {
+    id: string;
+    /** The owning org (null = the platform). */
+    owner_org_id: NullableDflt<string>;
+    /** The org it was created in; never changed. */
+    origin_org_id: NullableDflt<string>;
+    /** The owner shares it with other orgs. */
+    shareable: Dflt<boolean>;
+    catalog_item_id: NullableDflt<string>;
+    plugin_name: NullableDflt<string>;
+    name: string;
+    description: NullableDflt<string>;
+    description_zh: NullableDflt<string>;
+    current_version: number;
+    created_at: Ts;
+    updated_at: Ts;
+    deleted_at: TsNullable;
+}
+/**
+ * 0093: one version of a theme; `definition` is the parsed theme file, its fonts and logo live
+ * under `object_prefix` in `deployment/` (null without assets).
+ */
+export interface PlatformThemeVersionsTable {
+    theme_id: string;
+    version: number;
+    definition: Json<ParsedTheme>;
+    object_prefix: NullableDflt<string>;
+    catalog_version: NullableDflt<string>;
+    updated_on_own: Dflt<boolean>;
+    created_by: NullableDflt<string>;
+    created_at: Ts;
+}
 /** 0081: the orgs an own-scope `named` component is offered to. */
 export interface ComponentScopeOrgsTable {
     kind: ComponentKind;
@@ -1628,8 +1678,8 @@ export interface PluginInstallsTable {
  */
 export interface PluginInstallComponentsTable {
     install_id: string;
-    /** 0053: 'agent_template', ref = the agent_templates id. */
-    kind: "extension" | "connector" | "skill" | "plugin" | "agent_template";
+    /** 0053: 'agent_template', ref = the agent_templates id; 0093: 'theme', ref = the platform_themes id. */
+    kind: "extension" | "connector" | "skill" | "plugin" | "agent_template" | "theme";
     ref: string;
     created: boolean;
     skill_version: NullableCol<number>;

package/dist/errors.d.ts

@@ -108,6 +108,31 @@ export declare const ERROR_CODES: {
     /** What deleting an org's own plugin does changed since its preview (P3-19). */
     readonly "catalog.preview_stale": 409;
     readonly "catalog.name_conflict": 409;
+    /** A theme of an imported plugin fails its file or asset checks (themes spec §4, §5). */
+    readonly "theme.invalid": 400;
+    /** A theme of an imported plugin fails the readability checks of its merged schemes (§5). */
+    readonly "theme.unreadable": 400;
+    /**
+     * A settings write names a theme that is not available where it is set (§7, §9): an org default
+     * off in the org, a platform default that is not a platform theme with scope `all`, or a
+     * person's pick on in none of their orgs; details `[{ theme }]`.
+     */
+    readonly "theme.not_available": 400;
+    /**
+     * The change would take the platform default theme (`uiTheme`) away from an org: narrowing,
+     * disabling, removing it or its plugin (§7); details `[{ theme, setting: "uiTheme" }]`.
+     */
+    readonly "theme.platform_default": 409;
+    /**
+     * Another theme with the same id is already on in an org the change would turn this one on in
+     * (§6, rule 10); details `[{ theme, orgId, themes, plugins }]`.
+     */
+    readonly "theme.id_taken": 409;
+    /**
+     * A theme delivery URL names no stored theme version, or a file that version does not name (§8);
+     * a removed theme's versions are still served.
+     */
+    readonly "theme.not_found": 404;
     readonly "directory.not_configured": 409;
     readonly "catalog.item_disabled": 403;
     readonly "plugin.disabled": 409;
@@ -226,6 +251,8 @@ export declare const ERROR_CODES: {
     readonly "connector.tool_not_found": 404;
     readonly "connector.tool_not_pending": 409;
     readonly "connector.resources_disabled": 409;
+    /** Per-member tool policies on a connector with one org credential (decision 2026-11-09). */
+    readonly "connector.not_personal": 409;
     readonly "approval.not_found": 404;
     readonly "approval.already_decided": 409;
     readonly "approval.scope_not_allowed": 409;

package/dist/errors.js

@@ -108,6 +108,31 @@ export const ERROR_CODES = {
     /** What deleting an org's own plugin does changed since its preview (P3-19). */
     "catalog.preview_stale": 409,
     "catalog.name_conflict": 409,
+    /** A theme of an imported plugin fails its file or asset checks (themes spec §4, §5). */
+    "theme.invalid": 400,
+    /** A theme of an imported plugin fails the readability checks of its merged schemes (§5). */
+    "theme.unreadable": 400,
+    /**
+     * A settings write names a theme that is not available where it is set (§7, §9): an org default
+     * off in the org, a platform default that is not a platform theme with scope `all`, or a
+     * person's pick on in none of their orgs; details `[{ theme }]`.
+     */
+    "theme.not_available": 400,
+    /**
+     * The change would take the platform default theme (`uiTheme`) away from an org: narrowing,
+     * disabling, removing it or its plugin (§7); details `[{ theme, setting: "uiTheme" }]`.
+     */
+    "theme.platform_default": 409,
+    /**
+     * Another theme with the same id is already on in an org the change would turn this one on in
+     * (§6, rule 10); details `[{ theme, orgId, themes, plugins }]`.
+     */
+    "theme.id_taken": 409,
+    /**
+     * A theme delivery URL names no stored theme version, or a file that version does not name (§8);
+     * a removed theme's versions are still served.
+     */
+    "theme.not_found": 404,
     "directory.not_configured": 409,
     "catalog.item_disabled": 403,
     "plugin.disabled": 409,
@@ -226,6 +251,8 @@ export const ERROR_CODES = {
     "connector.tool_not_found": 404,
     "connector.tool_not_pending": 409,
     "connector.resources_disabled": 409,
+    /** Per-member tool policies on a connector with one org credential (decision 2026-11-09). */
+    "connector.not_personal": 409,
     "approval.not_found": 404,
     "approval.already_decided": 409,
     "approval.scope_not_allowed": 409,

package/dist/http/api.module.js

@@ -65,6 +65,9 @@ import { InvocableSkillsController } from "../skills/invocable.controller.js";
 import { SkillsController } from "../skills/skills.controller.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { StorageModule } from "../storage/storage.module.js";
+import { OrgThemesController } from "../themes/themes.controller.js";
+import { ThemesModule } from "../themes/themes.module.js";
+import { PlatformThemeController, ThemeDeliveryController, } from "../themes/themes-public.controller.js";
 import { ApprovalsController, ToolGrantsController } from "../tools/approvals.controller.js";
 import { ConnectorContentController } from "../tools/connector-content.controller.js";
 import { ConnectorsController } from "../tools/connectors.controller.js";
@@ -135,6 +138,9 @@ const CONTROLLERS = [
     OrgOwnedPluginsController,
     OrgComponentsController,
     AdminCatalogRequestsController,
+    OrgThemesController,
+    ThemeDeliveryController,
+    PlatformThemeController,
     DeviceAuthController,
 ];
 /**
@@ -168,6 +174,7 @@ ApiModule = __decorate([
             FilesModule,
             UiModule,
             InboxModule,
+            ThemesModule,
         ],
         controllers: CONTROLLERS,
         providers: [{ provide: APP_GUARD, useClass: AuthGuard }],

package/dist/identity/accounts.d.ts

@@ -100,17 +100,24 @@ export declare class AccountsService {
     verifyPassword(accountId: string, password: string): Promise<boolean>;
     get(id: string): Promise<Account | undefined>;
     /**
-     * A person's preferences (run context spec §3.4): `timeZone` is their time zone setting (IANA),
-     * null = follow the browser. Missing account → null.
+     * A person's preferences: `timeZone` is their time zone setting (IANA), null = follow the browser
+     * (run context spec §3.4); `theme` their theme (a `platform_themes` id), null = follow the org
+     * (themes spec §7). Missing account -> nulls.
      */
     preferences(accountId: string): Promise<{
         timeZone: string | null;
+        theme: string | null;
     }>;
-    /** Sets a person's preferences (the caller validated the time zone). */
+    /**
+     * Updates the preferences given (a field left out keeps its value; the caller validated the time
+     * zone). A theme must be on in at least one of the person's orgs, else 400 `theme.not_available`.
+     */
     setPreferences(accountId: string, prefs: {
-        timeZone: string | null;
+        timeZone?: string | null | undefined;
+        theme?: string | null | undefined;
     }): Promise<{
         timeZone: string | null;
+        theme: string | null;
     }>;
     /** 按 id 升序分页，`after` 为上一页最后一个 id。 */
     list(opts: {

package/dist/identity/accounts.js

@@ -15,6 +15,7 @@ import { ApiError } from "../errors.js";
 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 { assertThemeOnForAccount } from "../themes/theme-state.js";
 import { audit } from "./audit.js";
 import { MAX_PASSWORD_LENGTH, normalizeLogin, validatePassword } from "./login.js";
 import { DUMMY_PASSWORD_HASH, hashPassword, verifyPassword } from "./passwords.js";
@@ -237,24 +238,36 @@ let AccountsService = class AccountsService {
         return row && toAccount(row);
     }
     /**
-     * A person's preferences (run context spec §3.4): `timeZone` is their time zone setting (IANA),
-     * null = follow the browser. Missing account → null.
+     * A person's preferences: `timeZone` is their time zone setting (IANA), null = follow the browser
+     * (run context spec §3.4); `theme` their theme (a `platform_themes` id), null = follow the org
+     * (themes spec §7). Missing account -> nulls.
      */
     async preferences(accountId) {
         const row = await this.db
             .selectFrom("accounts")
-            .select("time_zone")
+            .select(["time_zone", "theme"])
             .where("id", "=", accountId)
             .executeTakeFirst();
-        return { timeZone: row?.time_zone ?? null };
+        return { timeZone: row?.time_zone ?? null, theme: row?.theme ?? null };
     }
-    /** Sets a person's preferences (the caller validated the time zone). */
+    /**
+     * Updates the preferences given (a field left out keeps its value; the caller validated the time
+     * zone). A theme must be on in at least one of the person's orgs, else 400 `theme.not_available`.
+     */
     async setPreferences(accountId, prefs) {
-        await this.db
-            .updateTable("accounts")
-            .set({ time_zone: prefs.timeZone, updated_at: new Date() })
-            .where("id", "=", accountId)
-            .execute();
+        if (prefs.theme != null)
+            await assertThemeOnForAccount(this.db.db, accountId, prefs.theme);
+        const set = {
+            ...(prefs.timeZone !== undefined && { time_zone: prefs.timeZone }),
+            ...(prefs.theme !== undefined && { theme: prefs.theme }),
+        };
+        if (Object.keys(set).length > 0) {
+            await this.db
+                .updateTable("accounts")
+                .set({ ...set, updated_at: new Date() })
+                .where("id", "=", accountId)
+                .execute();
+        }
         return this.preferences(accountId);
     }
     /** 按 id 升序分页，`after` 为上一页最后一个 id。 */

package/dist/identity/me.controller.d.ts

@@ -6,7 +6,7 @@ import { OrgsService } from "../orgs/orgs.service.js";
 import type { OrgRole } from "../orgs/roles.js";
 import { type Account, AccountsService } from "./accounts.js";
 import { type ApiTokenRecord, ApiTokenService } from "./api-tokens.js";
-import { type PreferencesSchema } from "./me.schemas.js";
+import { type Preferences, type PreferencesSchema } from "./me.schemas.js";
 import { type Principal } from "./principal.js";
 import { SessionService } from "./sessions.js";
 import { SettingsService } from "./settings.js";
@@ -46,16 +46,16 @@ export declare class MeController {
         canCreateOrg: boolean;
     }>;
     /**
-     * The person's preferences (run context spec §3.4): `timeZone` null = follow the browser's time
-     * zone sent with each message; a set zone overrides it for the messages sent afterwards.
+     * The person's preferences: `timeZone` null = follow the browser's time zone sent with each
+     * message, a set zone overrides it for the messages sent afterwards (run context spec §3.4);
+     * `theme` null = follow the org (themes spec §7).
      */
-    preferences(principal: Principal): Promise<{
-        timeZone: string | null;
-    }>;
-    /** Replaces the person's preferences; an unknown time zone → 400 `validation_failed`. */
-    setPreferences(principal: Principal, body: z.infer<typeof PreferencesSchema>): Promise<{
-        timeZone: string | null;
-    }>;
+    preferences(principal: Principal): Promise<Preferences>;
+    /**
+     * Updates the preferences given; a field left out keeps its value. An unknown time zone → 400
+     * `validation_failed`; a theme on in none of the person's orgs → 400 `theme.not_available`.
+     */
+    setPreferences(principal: Principal, body: z.infer<typeof PreferencesSchema>): Promise<Preferences>;
     /** 切换当前组织（仅 Web 会话）；`null` 清空。非成员或已软删除的组织 → `org.not_found`。 */
     setCurrentOrg(principal: Principal, body: z.infer<typeof CurrentOrgSchema>): Promise<void>;
     /**

package/dist/identity/me.controller.js

@@ -74,17 +74,19 @@ let MeController = class MeController {
         return { account: p.account, via: p.via, currentOrgId: current, memberships, canCreateOrg };
     }
     /**
-     * The person's preferences (run context spec §3.4): `timeZone` null = follow the browser's time
-     * zone sent with each message; a set zone overrides it for the messages sent afterwards.
+     * The person's preferences: `timeZone` null = follow the browser's time zone sent with each
+     * message, a set zone overrides it for the messages sent afterwards (run context spec §3.4);
+     * `theme` null = follow the org (themes spec §7).
      */
     async preferences(principal) {
         return this.accounts.preferences(requireUser(principal).account.id);
     }
-    /** Replaces the person's preferences; an unknown time zone → 400 `validation_failed`. */
+    /**
+     * Updates the preferences given; a field left out keeps its value. An unknown time zone → 400
+     * `validation_failed`; a theme on in none of the person's orgs → 400 `theme.not_available`.
+     */
     async setPreferences(principal, body) {
-        return this.accounts.setPreferences(requireUser(principal).account.id, {
-            timeZone: body.timeZone,
-        });
+        return this.accounts.setPreferences(requireUser(principal).account.id, body);
     }
     /** 切换当前组织（仅 Web 会话）；`null` 清空。非成员或已软删除的组织 → `org.not_found`。 */
     async setCurrentOrg(principal, body) {

package/dist/identity/me.schemas.d.ts

@@ -1,11 +1,21 @@
 import { z } from "zod";
 import type { RouteSchemas } from "../platform/route-schemas.js";
-/** `PUT /me/preferences`: the person's preferences (run context spec §3.4). */
+/**
+ * `PUT /me/preferences`: a partial update of the person's preferences; a field left out keeps its
+ * stored value (themes spec §9).
+ */
 export declare const PreferencesSchema: z.ZodObject<{
-    timeZone: z.ZodNullable<z.ZodString>;
+    timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
+/** The person's preferences as `GET` / `PUT /me/preferences` return them. */
+export interface Preferences {
+    timeZone: string | null;
+    theme: string | null;
+}
 declare const PreferencesBody_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
-    timeZone: z.ZodNullable<z.ZodString>;
+    timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>>;
 export declare class PreferencesBody extends PreferencesBody_base {
 }

package/dist/identity/me.schemas.js

@@ -1,11 +1,19 @@
 import { z } from "zod";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { IanaTimeZone } from "../time-zone.js";
-/** `PUT /me/preferences`: the person's preferences (run context spec §3.4). */
+/**
+ * `PUT /me/preferences`: a partial update of the person's preferences; a field left out keeps its
+ * stored value (themes spec §9).
+ */
 export const PreferencesSchema = z
     .object({
     /** The person's time zone (IANA); null = follow the browser (run context spec §3.4). */
-    timeZone: IanaTimeZone.nullable(),
+    timeZone: IanaTimeZone.nullable().optional(),
+    /**
+     * The person's theme (a `platform_themes` id on in at least one of their orgs, else 400
+     * `theme.not_available`); null = follow the org (themes spec §7).
+     */
+    theme: z.string().min(1).max(200).nullable().optional(),
 })
     .strict();
 export class PreferencesBody extends createZodDto(PreferencesSchema, "PreferencesBody") {

package/dist/identity/settings.d.ts

@@ -31,6 +31,18 @@ export declare const SUBAGENT_LIMIT_OVERRIDE: z.ZodObject<{
     maxTokensPerRun: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export type SubagentLimitOverride = z.infer<typeof SUBAGENT_LIMIT_OVERRIDE>;
+/** The deployment setting key of the platform default theme (themes spec §7). */
+export declare const UI_THEME_SETTING = "uiTheme";
+/**
+ * The platform default theme (themes spec §7): a `platform_themes` id, or null for the built-in
+ * theme. Only a platform-owned theme whose effective scope is `all` can be set (checked by
+ * {@link SettingsService.update}); every reader goes through {@link readUiTheme} or
+ * {@link SettingsService.get}, both parsing with this schema.
+ */
+export declare const UiThemeSetting: z.ZodObject<{
+    id: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type UiTheme = z.infer<typeof UiThemeSetting>;
 export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
     orgCreation: z.ZodDefault<z.ZodEnum<{
         anyone: "anyone";
@@ -57,6 +69,9 @@ export declare const DEPLOYMENT_SETTINGS: z.ZodObject<{
         deny: "deny";
     }>>;
     orgMarketplaceBrowse: z.ZodDefault<z.ZodBoolean>;
+    uiTheme: z.ZodDefault<z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type DeploymentSettings = z.infer<typeof DEPLOYMENT_SETTINGS>;
 /**
@@ -93,6 +108,9 @@ export declare const DEPLOYMENT_SETTINGS_PATCH: z.ZodObject<{
         deny: "deny";
     }>>;
     orgMarketplaceBrowse: z.ZodOptional<z.ZodBoolean>;
+    uiTheme: z.ZodOptional<z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type DeploymentSettingsPatch = z.infer<typeof DEPLOYMENT_SETTINGS_PATCH>;
 /**
@@ -118,6 +136,15 @@ export declare function assertCustomAllowed(db: KernelSchemaDb, key: "customConn
  * when there is one); missing or invalid -> the default, true.
  */
 export declare function readOrgMarketplaceBrowse(db: KernelSchemaDb): Promise<boolean>;
+/**
+ * The platform default theme setting, read live from PG (in the caller's transaction when there is
+ * one) and parsed with {@link UiThemeSetting}: missing or invalid -> `{ id: null }`. `lock`: the
+ * row is read FOR SHARE, so a concurrent write of the setting (which holds it FOR UPDATE) waits for
+ * the caller's transaction, and the reverse.
+ */
+export declare function readUiTheme(db: KernelSchemaDb, opts?: {
+    lock?: boolean;
+}): Promise<UiTheme>;
 /** Deployment settings: one row per key, defaults for missing keys. */
 export declare class SettingsService {
     private readonly db;

package/dist/identity/settings.js

@@ -14,6 +14,7 @@ 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 { KERNEL_LOGGER } from "../infra/tokens.js";
+import { assertPlatformDefaultEligible, lockThemeShared } from "../themes/theme-state.js";
 import { audit } from "./audit.js";
 import { SuperAdminLock } from "./super-admin.js";
 /** 币种代码：ISO 4217 的三位大写字母（如 USD、CNY）。 */
@@ -63,6 +64,15 @@ export const SUBAGENT_LIMIT_OVERRIDE = z
 });
 /** 组织能否自建连接器 / 技能（C22）：`deny` 时只能从平台目录安装（T26 执行）。 */
 const CustomPolicy = z.enum(["allow", "deny"]);
+/** The deployment setting key of the platform default theme (themes spec §7). */
+export const UI_THEME_SETTING = "uiTheme";
+/**
+ * The platform default theme (themes spec §7): a `platform_themes` id, or null for the built-in
+ * theme. Only a platform-owned theme whose effective scope is `all` can be set (checked by
+ * {@link SettingsService.update}); every reader goes through {@link readUiTheme} or
+ * {@link SettingsService.get}, both parsing with this schema.
+ */
+export const UiThemeSetting = z.object({ id: z.string().min(1).max(200).nullable() });
 export const DEPLOYMENT_SETTINGS = z.object({
     orgCreation: z.enum(["anyone", "super_admin"]).default("anyone"),
     /** 按组织覆盖运行并发上限（orgId → 上限）；未列出的组织用 `runtime.orgConcurrency`。 */
@@ -88,6 +98,8 @@ export const DEPLOYMENT_SETTINGS = z.object({
      * scope spec §5.1 rule 3). false hides the browse route and refuses those requests.
      */
     orgMarketplaceBrowse: z.boolean().default(true),
+    /** The platform default theme (themes spec §7); `{ id: null }`: the built-in theme. */
+    uiTheme: UiThemeSetting.default({ id: null }),
 });
 const DEFAULTS = DEPLOYMENT_SETTINGS.parse({});
 /**
@@ -114,6 +126,11 @@ export const DEPLOYMENT_SETTINGS_PATCH = z
     customConnectors: CustomPolicy.optional(),
     customSkills: CustomPolicy.optional(),
     orgMarketplaceBrowse: z.boolean().optional(),
+    /**
+     * The platform default theme: a platform-owned theme whose effective scope is `all`, not
+     * disabled (else 400 `theme.not_available`), or `{ id: null }` for the built-in theme.
+     */
+    uiTheme: UiThemeSetting.strict().optional(),
 })
     .strict();
 /**
@@ -191,6 +208,38 @@ export async function readOrgMarketplaceBrowse(db) {
     const parsed = z.boolean().safeParse(row.value);
     return parsed.success ? parsed.data : true;
 }
+/**
+ * The platform default theme setting, read live from PG (in the caller's transaction when there is
+ * one) and parsed with {@link UiThemeSetting}: missing or invalid -> `{ id: null }`. `lock`: the
+ * row is read FOR SHARE, so a concurrent write of the setting (which holds it FOR UPDATE) waits for
+ * the caller's transaction, and the reverse.
+ */
+export async function readUiTheme(db, opts = {}) {
+    let q = db.selectFrom("deployment_settings").select("value").where("key", "=", UI_THEME_SETTING);
+    if (opts.lock)
+        q = q.forShare();
+    const row = await q.executeTakeFirst();
+    const parsed = UiThemeSetting.safeParse(row?.value);
+    return parsed.success ? parsed.data : { id: null };
+}
+/**
+ * Locks the `uiTheme` row FOR UPDATE in the caller's transaction, creating it as `{ id: null }`
+ * first when it is missing (migration 0094 seeds it; a test may have truncated the table), so the
+ * FOR SHARE readers always find a row to wait on.
+ */
+async function lockUiThemeRow(db) {
+    await db
+        .insertInto("deployment_settings")
+        .values({ key: UI_THEME_SETTING, value: JSON.stringify({ id: null }) })
+        .onConflict((oc) => oc.column("key").doNothing())
+        .execute();
+    await db
+        .selectFrom("deployment_settings")
+        .select("key")
+        .where("key", "=", UI_THEME_SETTING)
+        .forUpdate()
+        .execute();
+}
 /** 按组织合并覆盖：值为 null 删除该组织，其余整项替换；未列出的组织不变。 */
 function mergeByOrg(current, patch) {
     const merged = { ...current };
@@ -267,6 +316,21 @@ let SettingsService = class SettingsService {
         if (patch.orgMarketplaceBrowse !== undefined) {
             next.orgMarketplaceBrowse = patch.orgMarketplaceBrowse;
         }
+        if (patch.uiTheme !== undefined) {
+            // The one theme lock order (themes spec §7), inside the super admin lock above: the chosen
+            // theme's catalog item, then its `platform_themes` row FOR SHARE, then the `uiTheme` row FOR
+            // UPDATE, and only then the eligibility check (on in every live org). The writers that take
+            // a theme away or switch it off in an org (scope, disable, removal, the org switch and
+            // uninstall) hold the item or theme row before they read `uiTheme` FOR SHARE, so they and
+            // this write wait for each other in the same order and never deadlock.
+            if (patch.uiTheme.id !== null)
+                await lockThemeShared(this.db.db, patch.uiTheme.id);
+            await lockUiThemeRow(this.db.db);
+            if (patch.uiTheme.id !== null) {
+                await assertPlatformDefaultEligible(this.db.db, patch.uiTheme.id);
+            }
+            next.uiTheme = { id: patch.uiTheme.id };
+        }
         const { runConcurrencyOverrides: runPatch, sandboxLimitOverrides: sandboxPatch, subagentLimitOverrides: subagentPatch, } = patch;
         if (runPatch !== undefined || sandboxPatch !== undefined || subagentPatch !== undefined) {
             const current = await this.get();

package/dist/orgs/settings.service.d.ts

@@ -19,6 +19,8 @@ import { OrgLock } from "./org-lock.js";
  *   `read-only` (writes listed as unavailable) or `off` (default `on`).
  * - `timeZone`: the org's default time zone (IANA; absent = UTC) for senders without one of their
  *   own (run context spec §3.3); an invalid stored value reads as absent.
+ * - `theme`: the org's default theme and whether members may pick their own (themes spec §7);
+ *   absent (or an invalid stored value) = follow the platform, personal picks allowed.
  */
 /** 组织沙箱出站白名单的主机数上限。 */
 export declare const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
@@ -34,6 +36,21 @@ export declare const SandboxEgressSettingSchema: z.ZodObject<{
     allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type SandboxEgressSetting = z.infer<typeof SandboxEgressSettingSchema>;
+/**
+ * The org's theme setting (themes spec §7): `id` a theme on in the org (a `platform_themes` id),
+ * null = follow the platform's default; `personal: "locked"` hides the personal picker in the org
+ * and resolution ignores personal picks there.
+ */
+export declare const OrgThemeSettingSchema: z.ZodObject<{
+    id: z.ZodNullable<z.ZodString>;
+    personal: z.ZodEnum<{
+        allowed: "allowed";
+        locked: "locked";
+    }>;
+}, z.core.$strict>;
+export type OrgThemeSetting = z.infer<typeof OrgThemeSettingSchema>;
+/** The theme setting of an org that has none: follow the platform, personal picks allowed. */
+export declare const DEFAULT_ORG_THEME: OrgThemeSetting;
 export declare const OrgSettingsSchema: z.ZodObject<{
     toolSearch: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
         off: "off";
@@ -61,6 +78,13 @@ export declare const OrgSettingsSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     wakeOnBackgroundTask: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
     timeZone: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    theme: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        personal: z.ZodEnum<{
+            allowed: "allowed";
+            locked: "locked";
+        }>;
+    }, z.core.$strict>>>;
 }, z.core.$strip>;
 export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
@@ -91,6 +115,13 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
     timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    theme: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        personal: z.ZodEnum<{
+            allowed: "allowed";
+            locked: "locked";
+        }>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type OrgSettingsPatch = z.infer<typeof OrgSettingsPatchSchema>;
 /** 部署的沙箱出站（`sandbox.limits.egress` + `allowHosts`）。 */