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

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";
@@ -60,6 +64,9 @@ import { OrgsModule } from "../orgs/orgs.module.js";
 import { OrgSettingsController } from "../orgs/settings.controller.js";
 import { RuntimeModule } from "../runtime/runtime.module.js";
 import { ConversationStreamController } from "../runtime/stream.controller.js";
+import { SetupModule } from "../setup/setup.module.js";
+import { SetupChecksController } from "../setup/setup-checks.controller.js";
+import { SetupGuidesController } from "../setup/setup-guides.controller.js";
 import { AgentSkillsController, InboxController, SkillChangesController, } from "../skills/changes.controller.js";
 import { InvocableSkillsController } from "../skills/invocable.controller.js";
 import { SkillsController } from "../skills/skills.controller.js";
@@ -138,6 +145,8 @@ const CONTROLLERS = [
     EvalRunsController,
     ModelPurposesController,
     OrgCatalogController,
+    SetupChecksController,
+    SetupGuidesController,
     OrgPluginUploadsController,
     OrgOwnedPluginsController,
     OrgComponentsController,
@@ -146,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
@@ -166,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,
@@ -179,6 +193,8 @@ ApiModule = __decorate([
             UiModule,
             InboxModule,
             ThemesModule,
+            ClientModule,
+            SetupModule,
         ],
         controllers: CONTROLLERS,
         providers: [{ provide: APP_GUARD, useClass: AuthGuard }],

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;

package/dist/identity/settings.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { EXTENSION_NAME_RE } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
@@ -74,6 +75,47 @@ export const UI_THEME_SETTING = "uiTheme";
  * {@link SettingsService.get}, both parsing with this schema.
  */
 export const UiThemeSetting = z.object({ id: z.string().min(1).max(200).nullable() });
+/** The deployment setting key of the client code kill switch (client extensions spec §10.2). */
+export const CLIENT_EXTENSIONS_SETTING = "clientExtensions";
+/** The plugins listed in `clientExtensions.disabled`: at most this many. */
+export const CLIENT_DISABLED_MAX = 200;
+const ClientDisabledList = z
+    .array(z.string().regex(EXTENSION_NAME_RE, "must be an extension name"))
+    .max(CLIENT_DISABLED_MAX);
+/**
+ * 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 const ClientExtensionsSetting = z.object({
+    enabled: z.boolean(),
+    disabled: ClientDisabledList,
+});
+/** The kill switch's default (and what a missing or invalid stored value reads as): everything on. */
+export const clientExtensionsDefault = () => ({
+    enabled: true,
+    disabled: [],
+});
+/**
+ * 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 function parseClientExtensions(value, log) {
+    if (value === undefined)
+        return clientExtensionsDefault();
+    const parsed = ClientExtensionsSetting.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    log?.warn("invalid deployment setting; using default", {
+        key: CLIENT_EXTENSIONS_SETTING,
+        issues: parsed.error.issues.map((i) => i.message),
+    });
+    return clientExtensionsDefault();
+}
 export const DEPLOYMENT_SETTINGS = z.object({
     orgCreation: z.enum(["anyone", "super_admin"]).default("anyone"),
     /** 按组织覆盖运行并发上限（orgId → 上限）；未列出的组织用 `runtime.orgConcurrency`。 */
@@ -101,8 +143,13 @@ export const DEPLOYMENT_SETTINGS = z.object({
     orgMarketplaceBrowse: z.boolean().default(true),
     /** The platform default theme (themes spec §7); `{ id: null }`: the built-in theme. */
     uiTheme: UiThemeSetting.default({ id: null }),
-    /** The platform default arrangement of UI slots (UI slots spec §5); orgs override per slot. */
+    /**
+     * The platform default arrangement of UI slots (UI slots spec §5): `{ hidden, order }` per list
+     * slot, `{ use }` per single slot (client extensions spec §6.3); orgs override per slot.
+     */
     uiArrangement: UiArrangementSchema.default({}),
+    /** The client code kill switch (client extensions spec §10.2). */
+    clientExtensions: ClientExtensionsSetting.default(clientExtensionsDefault),
 });
 const DEFAULTS = DEPLOYMENT_SETTINGS.parse({});
 /**
@@ -134,8 +181,22 @@ export const DEPLOYMENT_SETTINGS_PATCH = z
      * disabled (else 400 `theme.not_available`), or `{ id: null }` for the built-in theme.
      */
     uiTheme: UiThemeSetting.strict().optional(),
-    /** Per slot, the entry to hide / order contributions with; null removes a slot's entry. */
+    /**
+     * Per slot, the entry to hide / order contributions with (`{ use }` on a single slot); null
+     * removes a slot's entry.
+     */
     uiArrangement: UiArrangementPatchSchema.optional(),
+    /**
+     * The client code kill switch: each given field replaces the stored one (`disabled` is the
+     * whole list, stored sorted without duplicates); at least one field.
+     */
+    clientExtensions: z
+        .object({ enabled: z.boolean().optional(), disabled: ClientDisabledList.optional() })
+        .strict()
+        .refine((o) => o.enabled !== undefined || o.disabled !== undefined, {
+        message: "give enabled, disabled or both",
+    })
+        .optional(),
 })
     .strict();
 /**
@@ -258,6 +319,19 @@ export async function readUiArrangement(db) {
     const parsed = UiArrangementSchema.safeParse(row?.value);
     return parsed.success ? parsed.data : {};
 }
+/**
+ * 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 async function readClientExtensions(db, log) {
+    const row = await db
+        .selectFrom("deployment_settings")
+        .select("value")
+        .where("key", "=", CLIENT_EXTENSIONS_SETTING)
+        .executeTakeFirst();
+    return parseClientExtensions(row?.value, log);
+}
 /** 按组织合并覆盖：值为 null 删除该组织，其余整项替换；未列出的组织不变。 */
 function mergeByOrg(current, patch) {
     const merged = { ...current };
@@ -349,12 +423,21 @@ let SettingsService = class SettingsService {
             }
             next.uiTheme = { id: patch.uiTheme.id };
         }
-        const { runConcurrencyOverrides: runPatch, sandboxLimitOverrides: sandboxPatch, subagentLimitOverrides: subagentPatch, uiArrangement: arrangementPatch, } = patch;
+        const { runConcurrencyOverrides: runPatch, sandboxLimitOverrides: sandboxPatch, subagentLimitOverrides: subagentPatch, uiArrangement: arrangementPatch, clientExtensions: clientPatch, } = patch;
         if (runPatch !== undefined ||
             sandboxPatch !== undefined ||
             subagentPatch !== undefined ||
-            arrangementPatch !== undefined) {
+            arrangementPatch !== undefined ||
+            clientPatch !== undefined) {
             const current = await this.get();
+            if (clientPatch !== undefined) {
+                next.clientExtensions = {
+                    enabled: clientPatch.enabled ?? current.clientExtensions.enabled,
+                    disabled: clientPatch.disabled === undefined
+                        ? current.clientExtensions.disabled
+                        : [...new Set(clientPatch.disabled)].sort(),
+                };
+            }
             if (arrangementPatch !== undefined) {
                 next.uiArrangement = mergeArrangement(current.uiArrangement, arrangementPatch);
             }

package/dist/infra/lock/lock.service.d.ts

@@ -74,6 +74,14 @@ export declare class LockService {
     holderOf(key: string): Promise<string | null>;
     /** Deletes `key` when `holder` still owns it. */
     releaseIf(key: string, holder: string): Promise<boolean>;
+    /**
+     * Takes one of `limit` slots of the counting semaphore `key` for `holder` (a unique token), for at
+     * most `ttlMs` (a crashed holder's slot frees itself then; no renewal). False when every slot is
+     * taken. Release with {@link releaseSlot}.
+     */
+    takeSlot(key: string, holder: string, limit: number, ttlMs: number): Promise<boolean>;
+    /** Gives back `holder`'s slot of the semaphore `key` (nothing when it already expired). */
+    releaseSlot(key: string, holder: string): Promise<void>;
     /**
      * Takes `key` (no `lock:` prefix) with the caller's `holder` value for `ttlMs`, unless it is
      * held, and renews it every TTL/3 like {@link acquire} (a run longer than the TTL keeps it, a

package/dist/infra/lock/lock.service.js

@@ -20,6 +20,20 @@ import { ACQUIRE_EXCLUSIVE, ACQUIRE_SHARED, COUNT_SHARED_LEASES, DOWNGRADE_SHARE
 const RELEASE_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end`;
 /** Extends the key only while it holds our token. */
 const RENEW_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('pexpire', KEYS[1], tonumber(ARGV[2])) else return 0 end`;
+/**
+ * Takes a slot of a counting semaphore: a sorted set of holder tokens scored by expiry time. Expired
+ * holders (a crashed replica's) drop out first, so a slot is never lost for longer than its TTL;
+ * then the token is added when fewer than ARGV[2] slots are taken. The set itself expires with
+ * its last slot. KEYS[1] the set; ARGV: token, limit, ttl ms. Returns 1 when taken.
+ */
+const TAKE_SLOT = `local now = redis.call('time')
+local ms = tonumber(now[1]) * 1000 + math.floor(tonumber(now[2]) / 1000)
+redis.call('zremrangebyscore', KEYS[1], '-inf', ms)
+if redis.call('zcard', KEYS[1]) >= tonumber(ARGV[2]) then return 0 end
+redis.call('zadd', KEYS[1], ms + tonumber(ARGV[3]), ARGV[1])
+local last = redis.call('zrange', KEYS[1], -1, -1, 'withscores')
+redis.call('pexpireat', KEYS[1], tonumber(last[2]))
+return 1`;
 /** Resolves after `ms`; rejects with the abort reason when `signal` aborts first. */
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -117,6 +131,19 @@ let LockService = class LockService {
     async releaseIf(key, holder) {
         return (await this.redis.eval(RELEASE_IF, 1, key, holder)) === 1;
     }
+    /**
+     * Takes one of `limit` slots of the counting semaphore `key` for `holder` (a unique token), for at
+     * most `ttlMs` (a crashed holder's slot frees itself then; no renewal). False when every slot is
+     * taken. Release with {@link releaseSlot}.
+     */
+    async takeSlot(key, holder, limit, ttlMs) {
+        assertNoTransaction("takeSlot");
+        return ((await this.redis.eval(TAKE_SLOT, 1, key, holder, String(limit), String(Math.ceil(ttlMs)))) === 1);
+    }
+    /** Gives back `holder`'s slot of the semaphore `key` (nothing when it already expired). */
+    async releaseSlot(key, holder) {
+        await this.redis.zrem(key, holder);
+    }
     /**
      * Takes `key` (no `lock:` prefix) with the caller's `holder` value for `ttlMs`, unless it is
      * held, and renews it every TTL/3 like {@link acquire} (a run longer than the TTL keeps it, a

package/dist/infra/throttler/named-throttlers.d.ts

@@ -8,6 +8,8 @@ export interface NamedThrottler {
     ttl: number;
     /** The 429 message (today's text of the route that used the limiter). */
     message: string;
+    /** The 429 error code; default `auth.rate_limited` (the credential routes'). */
+    code?: "auth.rate_limited" | "rate_limited";
     /** The credential group: throttlers of one group are reserved together (one Redis hash tag). */
     group: string;
     /** What a successful attempt does to this counter: delete it, or give one attempt back. */
@@ -27,9 +29,14 @@ export interface NamedThrottler {
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
  * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
  *
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` opt in to
+ * `client-reports` with `@Throttled` (20 per minute per account: a crash loop in a browser must
+ * not flood the table).
+ *
  * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
  * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
- * credential: the device code is 32 random bytes).
+ * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`
+ * opts in to `setup-check` (setup guides v2 §10.3: each run may call a third party).
  */
 export declare const NAMED_THROTTLERS: readonly NamedThrottler[];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */

package/dist/infra/throttler/named-throttlers.js

@@ -30,9 +30,14 @@ const LOGIN_MSG = "Too many failed login attempts; try again later";
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
  * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
  *
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` opt in to
+ * `client-reports` with `@Throttled` (20 per minute per account: a crash loop in a browser must
+ * not flood the table).
+ *
  * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
  * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
- * credential: the device code is 32 random bytes).
+ * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`
+ * opts in to `setup-check` (setup guides v2 §10.3: each run may call a third party).
  */
 export const NAMED_THROTTLERS = [
     // (login, IP): 10; an attacker filling one login from one IP leaves the owner's other IPs alone (R25)
@@ -152,6 +157,30 @@ export const NAMED_THROTTLERS = [
         message: "Too many device code attempts; try again later",
         getTracker: (req) => sha256(principalAccountId(req)),
     },
+    // client code crash reports per signed-in account (counted before the handler): 20 / minute
+    {
+        name: "client-reports",
+        group: "client-reports",
+        onSuccess: "clear",
+        limit: 20,
+        ttl: 60_000,
+        message: "Too many client reports; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
+    // setup check runs per signed-in person (setup guides v2 §10.5): 30 a minute, every request
+    // counts (@Throttled); a cached answer costs no third-party call but still counts, as the page
+    // asks at most once per row and stale result. The edge of the route (with `retry-after`): the
+    // budget shared with the Platform tool's setup.check is SetupChecksService's own counter
+    {
+        name: "setup-check",
+        group: "setup-check",
+        onSuccess: "clear",
+        limit: 30,
+        ttl: 60_000,
+        message: "Too many setup check runs; try again in a minute",
+        code: "rate_limited",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
 ];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */
 export const throttlerKey = (name, tracker) => sha256(`${name}:${tracker}`);

package/dist/infra/throttler/throttler.guard.js

@@ -56,7 +56,7 @@ let KernelThrottlerGuard = class KernelThrottlerGuard extends ThrottlerGuard {
         const known = NAMED_THROTTLERS.find((t) => t.name === name);
         if (!known)
             throw new Error(`unknown throttler "${name}"`);
-        throw new ApiError("auth.rate_limited", known.message);
+        throw new ApiError(known.code ?? "auth.rate_limited", known.message);
     }
 };
 KernelThrottlerGuard = __decorate([

package/dist/kernel.module.js

@@ -9,6 +9,7 @@ import { Global, Module } from "@nestjs/common";
 import { APP_INTERCEPTOR } from "@nestjs/core";
 import { CatalogModule } from "./catalog/catalog.module.js";
 import { ChannelsModule } from "./channels/channels.module.js";
+import { ClientModule } from "./client/client.module.js";
 import { TitlesModule } from "./conversations/titles.js";
 import { ExtensionsModule } from "./extensions/extensions.module.js";
 import { ApiModule } from "./http/api.module.js";
@@ -111,6 +112,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 TitlesModule,
                 UsageReportModule,
                 ChannelsModule,
+                // client extensions: the client builds stored with extension packages
+                ClientModule,
                 // the @local sandbox provider, registered on every role (any replica may relay to a machine)
                 LocalDevicesModule,
                 // the Platform tool's operation registry and actor facts

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

@@ -87,19 +87,7 @@ export declare const OrgSettingsSchema: z.ZodObject<{
             locked: "locked";
         }>;
     }, z.core.$strict>>>;
-    uiArrangement: z.ZodCatch<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.ZodObject<{
-        hidden: z.ZodArray<z.ZodString>;
-        order: z.ZodArray<z.ZodString>;
-    }, z.core.$strict>>>>;
+    uiArrangement: z.ZodCatch<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>>, 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>>>>;
 }, z.core.$strip>;
 export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
@@ -137,19 +125,7 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
             locked: "locked";
         }>;
     }, 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>>>;
 }, z.core.$strict>;
 export type OrgSettingsPatch = z.infer<typeof OrgSettingsPatchSchema>;
 /** 部署的沙箱出站（`sandbox.limits.egress` + `allowHosts`）。 */

package/dist/overrides.d.ts

@@ -12,6 +12,7 @@ import { RUN_HOOKS, type RunHooks } from "./runtime/run-worker.js";
 import { SUBAGENT_MESSAGES_HOOKS, type SubagentMessagesHooks } from "./runtime/subagents/messages.js";
 import { USAGE_REPORT_RETRY, type UsageReportRetry } from "./runtime/usage-report.js";
 import { SANDBOX_LEASE_TIMINGS, type SandboxLeaseTimings } from "./sandbox/leases.js";
+import { SETUP_CHECK_TIMEOUT } from "./setup/setup-checks.service.js";
 import { TOOL_PIPELINE_HOOKS, type ToolPipelineHooks } from "./tools/pipeline.js";
 import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
 /**
@@ -24,7 +25,7 @@ import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
  * - `TOOL_PIPELINE_HOOKS`: the tool pipeline's hooks and policy decision;
  * - `SUBAGENT_MESSAGES_HOOKS`: the sub-agent message tools' hooks (a send raced by a run's end);
  * - `BOOTSTRAP_LOCK_TTL`, `FILE_PREVIEW_TIMEOUT`, `LIST_MODELS_TIMEOUT`, `USAGE_REPORT_RETRY`,
- *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`: shorter timings;
+ *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`, `SETUP_CHECK_TIMEOUT`: shorter timings;
  * - `EMBED_TOKEN_CLOCK`: the clock embed tokens are issued and checked with;
  * - `RUN_CONTEXT_CLOCK`: the clock run start reads the run context's date from, and the
  *   `CurrentTime` builtin the time;
@@ -42,6 +43,7 @@ interface KernelSeams {
     [USAGE_REPORT_RETRY]: UsageReportRetry;
     [SANDBOX_LEASE_TIMINGS]: Partial<SandboxLeaseTimings>;
     [CHANNEL_WEBHOOK_TIMINGS]: Partial<ChannelWebhookTimings>;
+    [SETUP_CHECK_TIMEOUT]: number;
     [EMBED_TOKEN_CLOCK]: () => number;
     [RUN_CONTEXT_CLOCK]: () => number;
     [APP_INTERCEPTOR]: NestInterceptor;

package/dist/overrides.js

@@ -10,6 +10,7 @@ import { RUN_HOOKS } from "./runtime/run-worker.js";
 import { SUBAGENT_MESSAGES_HOOKS, } from "./runtime/subagents/messages.js";
 import { USAGE_REPORT_RETRY } from "./runtime/usage-report.js";
 import { SANDBOX_LEASE_TIMINGS } from "./sandbox/leases.js";
+import { SETUP_CHECK_TIMEOUT } from "./setup/setup-checks.service.js";
 import { TOOL_PIPELINE_HOOKS } from "./tools/pipeline.js";
 import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
 const SEAM_TOKENS = [
@@ -24,6 +25,7 @@ const SEAM_TOKENS = [
     USAGE_REPORT_RETRY,
     SANDBOX_LEASE_TIMINGS,
     CHANNEL_WEBHOOK_TIMINGS,
+    SETUP_CHECK_TIMEOUT,
     EMBED_TOKEN_CLOCK,
     RUN_CONTEXT_CLOCK,
     APP_INTERCEPTOR,