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

package/dist/client/client.schemas.d.ts

@@ -0,0 +1,55 @@
+import { type UiSlotId } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas and response shapes of the client extension routes (spec §9.2). */
+/** `GET /api/v1/admin/ui/client?plugin=`: at most that plugin's platform set. */
+export declare const AdminClientQuery: z.ZodObject<{
+    plugin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One file URL of a client build, with the integrity recorded when the package was stored. */
+export interface ClientFileRef {
+    url: string;
+    integrity: string;
+}
+/** One extension of a shell read: its build's files and the components the viewer may use. */
+export interface ClientExtensionItem {
+    plugin: string;
+    /** The package sha256: the build id in the file URLs. */
+    build: string;
+    entry: ClientFileRef | null;
+    /** Empty in the admin set (spec §9.6). */
+    styles: ClientFileRef[];
+    components: {
+        id: string;
+        slot: UiSlotId;
+    }[];
+}
+/** The shell read (spec §9.2). */
+export interface ClientExtensionsResponse {
+    /** False under the kill switch: `items` is then empty. */
+    enabled: boolean;
+    /** The host's `CLIENT_API_VERSION`, echoed for diagnostics. */
+    apiVersion: number;
+    items: ClientExtensionItem[];
+}
+/** The most characters of a report's `message` (spec §10.4): longer is refused, not truncated. */
+export declare const REPORT_MESSAGE_MAX = 500;
+/**
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` (spec
+ * §10.4): one crash or load report of client code, from the browser that ran it. `build` is the
+ * package sha256 the files were loaded from; `contribution` the component id (null: the whole
+ * extension, e.g. the entry failed to load), which must be a component of that build's manifest.
+ */
+export declare const ReportBody: z.ZodObject<{
+    plugin: z.ZodString;
+    build: z.ZodString;
+    contribution: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        api: "api";
+        budget: "budget";
+        event: "event";
+        load: "load";
+        render: "render";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type ReportBodyInput = z.infer<typeof ReportBody>;

package/dist/client/client.schemas.js

@@ -0,0 +1,27 @@
+import { EXTENSION_NAME_RE } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas and response shapes of the client extension routes (spec §9.2). */
+/** `GET /api/v1/admin/ui/client?plugin=`: at most that plugin's platform set. */
+export const AdminClientQuery = z.object({
+    plugin: z.string().regex(EXTENSION_NAME_RE, "must be an extension name").optional(),
+});
+/** The most characters of a report's `message` (spec §10.4): longer is refused, not truncated. */
+export const REPORT_MESSAGE_MAX = 500;
+/** The UI contribution id grammar of the SDK (`ui[].id`): what a report's `contribution` names. */
+const COMPONENT_ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+/**
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` (spec
+ * §10.4): one crash or load report of client code, from the browser that ran it. `build` is the
+ * package sha256 the files were loaded from; `contribution` the component id (null: the whole
+ * extension, e.g. the entry failed to load), which must be a component of that build's manifest.
+ */
+export const ReportBody = z.object({
+    plugin: z.string().regex(EXTENSION_NAME_RE, "must be an extension name"),
+    build: z.string().regex(/^[0-9a-f]{64}$/, "must be a 64-character lowercase hex sha256"),
+    contribution: z
+        .string()
+        .regex(COMPONENT_ID_RE, "must be a component id of the build (or null)")
+        .nullable(),
+    kind: z.enum(["load", "render", "event", "api", "budget"]),
+    message: z.string().max(REPORT_MESSAGE_MAX),
+});

package/dist/ctx/create-ctx.d.ts

@@ -1,4 +1,4 @@
-import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, resolveUiSlots, type ToolHandler, type ToolSpec } from "@capybara-hq/plugin-sdk";
+import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, resolveUiSlots, type SetupCheckArgs, type SetupGuidePlace, type ToolHandler, type ToolSpec } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { Kysely } from "kysely";
 import { type RegisteredHook } from "../extensions/hooks.js";
@@ -52,6 +52,15 @@ export type RegisteredTool = {
     spec: ToolSpec;
     handler: ToolHandler;
 };
+/**
+ * A setup check registered through `ctx.setup.check`: `place` and `run` read once from the
+ * definition at registration and frozen, so the extension cannot swap them afterwards (a getter
+ * on the definition runs once, at registration, never when a check runs).
+ */
+export type RegisteredSetupCheck = Readonly<{
+    place: SetupGuidePlace;
+    run: (args: SetupCheckArgs) => Promise<unknown>;
+}>;
 /** 插件经 `ctx.extensionPoints` 取用其他插件能力时，内核注入的访问接口。 */
 export interface ExtensionPointAccess {
     /** 已加载（setup 完成）的提供方，按加载顺序；按完整引用（含主版本）精确匹配。 */
@@ -105,7 +114,11 @@ export type KernelExtensionContext = ExtensionContext & {
     uiViews: ReadonlyMap<string, UiRender>;
     /** 经 `ctx.ui.action` 注册的动作处理函数（按贡献 id）。 */
     uiActions: ReadonlyMap<string, UiActionHandler>;
-    /** setup 结束后调用：此后 `tools.register`、`ui.view`、`ui.action`、`hooks.on` 抛错。 */
+    /** Setup checks registered through `ctx.setup.check`, by id. */
+    setupChecks: ReadonlyMap<string, RegisteredSetupCheck>;
+    /**
+     * setup 结束后调用：此后 `tools.register`、`ui.view`、`ui.action`、`hooks.on`、`setup.check` 抛错。
+     */
     sealTools(): void;
     /** 中止 signal、封账并逐项撤销仍在账上的登记、关闭队列连接（幂等）。 */
     close(): Promise<void>;
@@ -127,8 +140,10 @@ export declare class LiveConfig {
  * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
  *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
- *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
- *   setup only); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
+ *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` or
+ *   `permissions.ui.components` (a component's server view; during setup only); `setup.check` only
+ *   ids declared in `permissions.setupChecks` (during setup only, `place` and `run` read once and
+ *   frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
  *   replicas; `ui.verifyEmbedToken` checks an embed token the kernel signed: `claims.plugin` must be
  *   this extension, the extension still enabled in that org and the caller still an active member of
  *   the org (org not deleted); returns the current role;

package/dist/ctx/create-ctx.js

@@ -1,4 +1,4 @@
-import { EXTENSION_POINTS, ExtensionPermissionError, ExtensionPointUnavailableError, FILE_PREVIEW_EXTENSION_POINT, OBJECT_STORE_EXTENSION_POINT, parseExtensionPoint, resolveUiSlots, validateFilePreviewProvider, validateToolSpec, } from "@capybara-hq/plugin-sdk";
+import { EXTENSION_POINTS, ExtensionPermissionError, ExtensionPointUnavailableError, FILE_PREVIEW_EXTENSION_POINT, OBJECT_STORE_EXTENSION_POINT, parseExtensionPoint, resolveUiSlots, SETUP_CHECK_ID_RE, SETUP_GUIDE_PLACES, validateFilePreviewProvider, validateToolSpec, } from "@capybara-hq/plugin-sdk";
 import { Command, ConnectionBuilder, ControlledTransactionBuilder, Kysely, TransactionBuilder, } from "kysely";
 import { conversationTopic } from "../conversations/event-log.js";
 import { kernelDb } from "../db/kernel-schema.js";
@@ -181,8 +181,10 @@ export class LiveConfig {
  * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
  *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
- *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
- *   setup only); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
+ *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` or
+ *   `permissions.ui.components` (a component's server view; during setup only); `setup.check` only
+ *   ids declared in `permissions.setupChecks` (during setup only, `place` and `run` read once and
+ *   frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
  *   replicas; `ui.verifyEmbedToken` checks an embed token the kernel signed: `claims.plugin` must be
  *   this extension, the extension still enabled in that org and the caller still an active member of
  *   the org (org not deleted); returns the current role;
@@ -261,6 +263,8 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
         ...(manifest.optional ?? []),
     ]);
     const uiReg = new PluginUiRegistration(manifest, deny);
+    const declaredSetupChecks = new Set(perms.setupChecks ?? []);
+    const setupChecks = new Map();
     const embedTokens = deps.embedTokens;
     const uiResolution = resolveUiSlots(manifest.ui);
     const uiSlots = new Map(uiResolution.resolved.map((r) => [r.contribution.id, r.slot]));
@@ -445,6 +449,49 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
                 });
             },
         },
+        // Setup checks (setup guides v2 §10.2): only during setup, only ids declared in
+        // permissions.setupChecks (an undeclared or malformed id is a denial, audited); the kernel's
+        // SetupChecksService runs them (bounded, cached, redacted).
+        setup: {
+            check(id, def) {
+                if (toolsSealed) {
+                    throw new Error(`plugin ${name}: setup.check is only allowed during setup; setup has completed`);
+                }
+                if (typeof id !== "string" || !SETUP_CHECK_ID_RE.test(id) || !declaredSetupChecks.has(id)) {
+                    // the item names the id only when it has the id shape (an audit row never carries
+                    // arbitrary extension text)
+                    deny(`permissions.setupChecks ${typeof id === "string" && SETUP_CHECK_ID_RE.test(id) ? id : "(invalid id)"}`);
+                }
+                if (setupChecks.has(id)) {
+                    throw new Error(`plugin ${name}: duplicate setup check "${id}"`);
+                }
+                if (typeof def !== "object" || def === null) {
+                    throw new Error(`plugin ${name}: setup check "${id}" needs a definition object`);
+                }
+                // read once: what runs later is exactly what was checked here
+                const place = def.place;
+                const run = def.run;
+                if (!SETUP_GUIDE_PLACES.includes(place)) {
+                    throw new Error(`plugin ${name}: setup check "${id}" place must be one of ${SETUP_GUIDE_PLACES.join(", ")}`);
+                }
+                if (typeof run !== "function") {
+                    throw new Error(`plugin ${name}: setup check "${id}" run must be a function`);
+                }
+                const check = Object.freeze({
+                    place: place,
+                    run: run,
+                });
+                setupChecks.set(id, check);
+                ledger.add({
+                    kind: "setup.check",
+                    key: id,
+                    dispose: async () => {
+                        if (setupChecks.get(id) === check)
+                            setupChecks.delete(id);
+                    },
+                });
+            },
+        },
         hooks: {
             on(mount, handler, opts) {
                 if (toolsSealed) {
@@ -585,6 +632,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
         uiResolution,
         uiViews: uiReg.views,
         uiActions: uiReg.actions,
+        setupChecks,
         ledger,
         async beginDispose(deadline) {
             drainDeadline = deadline;

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

@@ -419,6 +419,11 @@ export interface ConnectorsTable {
     template_tool_policies: ColumnType<Record<string, "allow" | "ask" | "deny"> | null, string | null | undefined, string | null>;
     /** 0081: the platform connector template this connector was made from (null = none). */
     platform_template_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * 0106: the setup guide of its connector template it was last set up with (`{ guideId, version,
+     * hash, mode: null }`); null when unknown (custom connectors, connectors before 0106).
+     */
+    guide_ack: ColumnType<GuideAckJson | null, string | null | undefined, string | null>;
 }
 /**
  * 0104: a member's own policy for one tool of a personal-credential connector, for calls made with
@@ -567,12 +572,16 @@ export interface LgCheckpointWritesTable {
     task_path: Generated<string>;
 }
 /** 0018_channels.sql：组织的渠道连接（非密钥配置；密钥在 secrets `channels:<id>:config`）。 */
-/** `channel_connections.guide_ack` (0099): the setup guide a connection was set up with. */
+/**
+ * `channel_connections.guide_ack` (0099) and `connectors.guide_ack` (0106): the setup guide a
+ * target was set up with; `hash` is the v2 drift hash (`setupGuideHash`, admin audience) of
+ * `mode` (null for a place without modes).
+ */
 export interface GuideAckJson {
     guideId: string;
     version: string;
     hash: string;
-    mode: string;
+    mode: string | null;
 }
 export interface ChannelConnectionsTable {
     id: string;
@@ -1094,6 +1103,12 @@ export interface ExtensionReplicaStatusTable {
     detail: string | null;
     /** The old version this replica still serves when this row's version did not load (see migration 0030). */
     serving_version: Generated<string | null>;
+    /**
+     * 0107: the package sha256 this replica actually serves for the plugin (the row's `sha256` when
+     * loaded, the older package still running when the row's version is pending or failed, null when
+     * none runs). Client code is delivered for the package a live replica serves.
+     */
+    serving_sha256: Generated<string | null>;
     http_replica_id: string | null;
     heartbeat_at: Ts;
 }
@@ -1225,6 +1240,42 @@ export interface KernelDatabase {
     org_notices: OrgNoticesTable;
     platform_notices: PlatformNoticesTable;
     plugin_scope_sync_failures: PluginScopeSyncFailuresTable;
+    extension_client_builds: ExtensionClientBuildsTable;
+    extension_client_reports: ExtensionClientReportsTable;
+}
+/**
+ * 0107: the client files of an extension package (client extensions spec §9.1), keyed by the
+ * package sha256 (the build id). Paths are the manifest keys (`./dist/client/...`); the files live
+ * in object storage under `deployment/<object_prefix>`.
+ */
+export interface ExtensionClientBuildsTable {
+    package_sha256: string;
+    plugin: string;
+    /** `./dist/client/client.mjs`, or null for CSS-only decoration. */
+    entry: string | null;
+    styles: ColumnType<string[], string[], string[]>;
+    assets: ColumnType<string[], string[], string[]>;
+    /** Manifest key -> `sha384-<base64>`, checked against the bytes when stored. */
+    integrity: Json<Record<string, string>>;
+    /** Manifest key -> size in bytes. */
+    sizes: Json<Record<string, number>>;
+    api_version: number;
+    /** Relative to `deployment/`: `platform/client/<plugin>/<sha256>/`. */
+    object_prefix: string;
+    created_at: Ts;
+}
+/** 0107: crash and load reports of client code (client extensions spec §10.4). */
+export interface ExtensionClientReportsTable {
+    plugin: string;
+    build: string;
+    /** Null for admin pages. */
+    org_id: string | null;
+    contribution: string | null;
+    kind: "load" | "render" | "event" | "api" | "budget";
+    count: Generated<number>;
+    first_at: Ts;
+    last_at: Ts;
+    last_message: string;
 }
 /** 0082: one run of the platform components migration job (`catalog/platform-migration.ts`). */
 export interface PlatformMigrationRunsTable {
@@ -1520,6 +1571,11 @@ export interface CatalogItemVersionsTable {
     applied_at: TsNullable;
     /** 0084 (ruling P3-52): when the super admin rejected this pending org version. */
     rejected_at: TsNullable;
+    /**
+     * 0107: the keys of `suggestedAppearance.replacements` in plugin.json order (jsonb does not keep
+     * key order); null without replacements.
+     */
+    appearance_order: ColumnType<string[] | null, string[] | null | undefined, string[] | null>;
 }
 /** 0035_catalogs.sql, renamed in 0042: marketplaces (official / custom). */
 export interface MarketplacesTable {

package/dist/errors.d.ts

@@ -133,6 +133,35 @@ export declare const ERROR_CODES: {
      * a removed theme's versions are still served.
      */
     readonly "theme.not_found": 404;
+    /**
+     * An `extension.client` section whose extension manifest lacks `permissions.client: true`
+     * (client extensions spec §5.4: client code is always declared and reviewed).
+     */
+    readonly "client.undeclared": 400;
+    /**
+     * A client file's sha384 is not the integrity its plugin.json records (spec §9.1); details
+     * `[{ file }]` (the manifest key).
+     */
+    readonly "client.integrity_mismatch": 400;
+    /**
+     * The client section or a client file fails the import checks (spec §4.1, §9.1: a listed file
+     * missing, a file not listed, a key that cannot be looked up exactly, a size limit, a stylesheet
+     * not wrapped in `@layer extensions` or with `@import` / an absolute `url()`); details
+     * `[{ file, reason }]`.
+     */
+    readonly "client.invalid": 400;
+    /**
+     * The client section's `apiVersion` is newer than the deployment's `CLIENT_API_VERSION` (spec
+     * §4.2): the web host could not run the bundle; details `[{ apiVersion, supported }]`.
+     */
+    readonly "client.api_unsupported": 400;
+    /**
+     * A client file URL (`/api/v1/client/<plugin>/<build>/<file>`, spec §9.3) the caller may not
+     * fetch: an unknown or old build, a file the build does not list (by its exact key), an extension
+     * not running or not approved, not enabled in any live org the caller belongs to, or stopped by
+     * the kill switch. One code for all, so nothing tells them apart.
+     */
+    readonly "client.not_found": 404;
     readonly "directory.not_configured": 409;
     readonly "catalog.item_disabled": 403;
     readonly "plugin.disabled": 409;
@@ -159,6 +188,8 @@ export declare const ERROR_CODES: {
     readonly "catalog.not_deployed": 409;
     readonly "catalog.icon_not_found": 404;
     readonly "catalog.guide_not_found": 404;
+    /** The check is not in the setup guide rendered for that mode and audience (setup guides v2 §10.3). */
+    readonly "catalog.check_not_found": 404;
     readonly "marketplace.not_found": 404;
     readonly "marketplace.entry_not_found": 404;
     readonly "marketplace.fetch_failed": 502;
@@ -246,6 +277,8 @@ export declare const ERROR_CODES: {
     readonly "background_task.output_unavailable": 409;
     readonly "connector.not_found": 404;
     readonly "connector.slug_taken": 409;
+    /** The connector template's setup guide moved on since the person was shown it (guide-ack). */
+    readonly "connector.guide_changed": 409;
     readonly "connector.kind_unavailable": 409;
     readonly "connector.connect_failed": 502;
     readonly "connector.tool_not_found": 404;

package/dist/errors.js

@@ -133,6 +133,35 @@ export const ERROR_CODES = {
      * a removed theme's versions are still served.
      */
     "theme.not_found": 404,
+    /**
+     * An `extension.client` section whose extension manifest lacks `permissions.client: true`
+     * (client extensions spec §5.4: client code is always declared and reviewed).
+     */
+    "client.undeclared": 400,
+    /**
+     * A client file's sha384 is not the integrity its plugin.json records (spec §9.1); details
+     * `[{ file }]` (the manifest key).
+     */
+    "client.integrity_mismatch": 400,
+    /**
+     * The client section or a client file fails the import checks (spec §4.1, §9.1: a listed file
+     * missing, a file not listed, a key that cannot be looked up exactly, a size limit, a stylesheet
+     * not wrapped in `@layer extensions` or with `@import` / an absolute `url()`); details
+     * `[{ file, reason }]`.
+     */
+    "client.invalid": 400,
+    /**
+     * The client section's `apiVersion` is newer than the deployment's `CLIENT_API_VERSION` (spec
+     * §4.2): the web host could not run the bundle; details `[{ apiVersion, supported }]`.
+     */
+    "client.api_unsupported": 400,
+    /**
+     * A client file URL (`/api/v1/client/<plugin>/<build>/<file>`, spec §9.3) the caller may not
+     * fetch: an unknown or old build, a file the build does not list (by its exact key), an extension
+     * not running or not approved, not enabled in any live org the caller belongs to, or stopped by
+     * the kill switch. One code for all, so nothing tells them apart.
+     */
+    "client.not_found": 404,
     "directory.not_configured": 409,
     "catalog.item_disabled": 403,
     "plugin.disabled": 409,
@@ -159,6 +188,8 @@ export const ERROR_CODES = {
     "catalog.not_deployed": 409,
     "catalog.icon_not_found": 404,
     "catalog.guide_not_found": 404,
+    /** The check is not in the setup guide rendered for that mode and audience (setup guides v2 §10.3). */
+    "catalog.check_not_found": 404,
     "marketplace.not_found": 404,
     "marketplace.entry_not_found": 404,
     "marketplace.fetch_failed": 502,
@@ -246,6 +277,8 @@ export const ERROR_CODES = {
     "background_task.output_unavailable": 409,
     "connector.not_found": 404,
     "connector.slug_taken": 409,
+    /** The connector template's setup guide moved on since the person was shown it (guide-ack). */
+    "connector.guide_changed": 409,
     "connector.kind_unavailable": 409,
     "connector.connect_failed": 502,
     "connector.tool_not_found": 404,

package/dist/extensions/admin-ops.d.ts

@@ -125,7 +125,9 @@ export declare class ExtensionAdminOps {
      * fix: clearing them would let org enablement bypass catalog policy, C22). The detail of the
      * `extension.installed` audit carries `catalogItemId`; when it already points at the same package
      * and only the source item changed, only that column changes, audit
-     * `extension.install_source_changed`.
+     * `extension.install_source_changed`. With `opts.liveItem` (an org upload's confirmation) a
+     * source item gone or removed when its row lock is granted -> 409 `catalog.item_removed`, before
+     * anything is written.
      * A version change of an enabled extension whose new version provides a single-provider
      * extension point the old one did not, while another extension holds it: the new version is
      * installed **disabled** (`enabled_at` cleared, audit `extension.disabled` with `singleProvider`)
@@ -135,6 +137,7 @@ export declare class ExtensionAdminOps {
      */
     install(name: string, sha256: string, actor: string | null, actorTokenId?: string, opts?: {
         catalogItemId?: string;
+        liveItem?: true;
         owner?: ExtensionOpsOwner;
     }): Promise<InstallView>;
     private writeInstall;

package/dist/extensions/admin-ops.js

@@ -112,7 +112,9 @@ let ExtensionAdminOps = class ExtensionAdminOps {
      * fix: clearing them would let org enablement bypass catalog policy, C22). The detail of the
      * `extension.installed` audit carries `catalogItemId`; when it already points at the same package
      * and only the source item changed, only that column changes, audit
-     * `extension.install_source_changed`.
+     * `extension.install_source_changed`. With `opts.liveItem` (an org upload's confirmation) a
+     * source item gone or removed when its row lock is granted -> 409 `catalog.item_removed`, before
+     * anything is written.
      * A version change of an enabled extension whose new version provides a single-provider
      * extension point the old one did not, while another extension holds it: the new version is
      * installed **disabled** (`enabled_at` cleared, audit `extension.disabled` with `singleProvider`)
@@ -159,6 +161,23 @@ let ExtensionAdminOps = class ExtensionAdminOps {
     async writeInstall(name, sha256, pkg, target, actor, actorTokenId, opts) {
         const db = this.db;
         await this.authorize(actor, opts.owner);
+        // The source item's row before the install lock (the global lock order: the item, then the
+        // install lock; ruling P3-50): the catalog source and install rows written below check it by
+        // foreign key (FOR KEY SHARE), and an org deletion or an item removal holds it FOR UPDATE
+        // while it waits for the install lock (CatalogService.removeIn). Taken after the install lock
+        // instead, the two deadlock (40P01).
+        if (opts.catalogItemId !== undefined) {
+            const item = await db
+                .selectFrom("catalog_items")
+                .select("deleted_at")
+                .where("id", "=", opts.catalogItemId)
+                .forKeyShare()
+                .executeTakeFirst();
+            // The lock waits out a removal holding the row; the row read then is the removed one
+            if (opts.liveItem && (item === undefined || item.deleted_at !== null)) {
+                throw new ApiError("catalog.item_removed", `${name} was removed while its confirmation was running; nothing of it stays installed`);
+            }
+        }
         const row = await this.lockRow(name);
         // 不经目录重装时保留原来的来源条目（不清空，C22）
         const catalogItemId = opts.catalogItemId ?? row?.catalog_item_id ?? null;
@@ -520,6 +539,8 @@ function fallbackView(name, known, err) {
         builtin: false,
         installSource: null,
         uiDropped: [],
+        client: null,
+        clientReports: [],
         error: `the change was saved, but its current status cannot be read: ${err instanceof Error ? err.message : String(err)}`,
     };
 }

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

@@ -126,4 +126,12 @@ export declare class ExtensionAdmin {
      */
     private orgsNeedingConfig;
     private views;
+    /**
+     * The client build of each subject and its newest reports (at most {@link CLIENT_REPORTS_SHOWN}
+     * per extension, limited in SQL), in two queries over all subjects. The build is the one a live
+     * replica serves (`serving_sha256` of the fresh rows `live`, like the shell reads: the install's
+     * own package when it runs, else the newest still served, e.g. the old one beside an upgrade
+     * awaiting approval or failed); with none served, the install record package's build.
+     */
+    private clientsOf;
 }

package/dist/extensions/admin-view.js

@@ -37,6 +37,8 @@ import { SingleProviderGuard } from "./single-provider.js";
 export { PLUGINS_CHANGED_TOPIC };
 /** 内容寻址的包 → 权限集合（包不可变，缓存安全；只作缓存，不是跨副本状态）。 */
 const PACKAGE_SET_CACHE_MAX = 256;
+/** The most client reports an extension view lists (the newest). */
+const CLIENT_REPORTS_SHOWN = 50;
 /** 空权限集合（包读不到的降级项）。 */
 const EMPTY_SET = buildPermissionSet({
     provides: [],
@@ -390,8 +392,13 @@ let ExtensionAdmin = class ExtensionAdmin {
             .where("en.plugin", "in", names)
             .groupBy("en.plugin")
             .execute()).map((r) => [r.plugin, Number(r.n)]));
+        const { clients, reports } = await this.clientsOf(subjects, rows);
         return subjects.map((s) => {
             const of = items.get(s.name);
+            const clientFields = {
+                client: clients.get(s.name) ?? null,
+                clientReports: reports.get(s.name) ?? [],
+            };
             const builtin = of?.some((i) => i.builtin) === true || s.install?.required === true;
             const scopeInfo = {
                 scope: of?.[0]
@@ -441,6 +448,7 @@ let ExtensionAdmin = class ExtensionAdmin {
                     ...scopeInfo,
                     installSource: install?.source ?? null,
                     uiDropped: this.host.uiDropped(s.name),
+                    ...clientFields,
                     error: s.broken,
                 };
             }
@@ -495,9 +503,79 @@ let ExtensionAdmin = class ExtensionAdmin {
                 ...scopeInfo,
                 installSource: install?.source ?? null,
                 uiDropped: this.host.uiDropped(s.name),
+                ...clientFields,
             };
         });
     }
+    /**
+     * The client build of each subject and its newest reports (at most {@link CLIENT_REPORTS_SHOWN}
+     * per extension, limited in SQL), in two queries over all subjects. The build is the one a live
+     * replica serves (`serving_sha256` of the fresh rows `live`, like the shell reads: the install's
+     * own package when it runs, else the newest still served, e.g. the old one beside an upgrade
+     * awaiting approval or failed); with none served, the install record package's build.
+     */
+    async clientsOf(subjects, live) {
+        const targets = subjects.flatMap((s) => {
+            if (s.install === undefined || s.install === null || s.broken !== undefined)
+                return [];
+            const serving = new Set(live.flatMap((r) => r.plugin === s.name && r.serving_sha256 !== null ? [r.serving_sha256] : []));
+            return [{ plugin: s.name, sha: s.install.sha256, serving }];
+        });
+        const clients = new Map();
+        const reports = new Map();
+        if (targets.length === 0)
+            return { clients, reports };
+        const shas = [...new Set(targets.flatMap((t) => [t.sha, ...t.serving]))];
+        const builds = await this.db
+            .selectFrom("extension_client_builds")
+            .select(["package_sha256", "plugin", "sizes", "api_version", "created_at"])
+            .where("package_sha256", "in", shas)
+            .orderBy("created_at", "desc")
+            .execute();
+        for (const t of targets) {
+            const mine = builds.filter((x) => x.plugin === t.plugin);
+            const b = (t.serving.has(t.sha) ? mine.find((x) => x.package_sha256 === t.sha) : undefined) ??
+                mine.find((x) => t.serving.has(x.package_sha256)) ??
+                (t.serving.size === 0 ? mine.find((x) => x.package_sha256 === t.sha) : undefined);
+            if (b === undefined)
+                continue;
+            clients.set(t.plugin, {
+                build: b.package_sha256,
+                files: Object.entries(b.sizes)
+                    .map(([path, bytes]) => ({ path, bytes }))
+                    .sort((x, y) => x.path.localeCompare(y.path)),
+                apiVersion: b.api_version,
+            });
+        }
+        const built = [...clients].map(([plugin, c]) => ({ plugin, build: c.build }));
+        if (built.length === 0)
+            return { clients, reports };
+        const ranked = this.db
+            .selectFrom("extension_client_reports")
+            .selectAll()
+            .select(sql `row_number() over (partition by plugin order by last_at desc)`.as("rank"))
+            .where((eb) => eb.or(built.map((c) => eb.and([eb("plugin", "=", c.plugin), eb("build", "=", c.build)]))));
+        const rows = await this.db
+            .selectFrom(ranked.as("r"))
+            .selectAll()
+            .where("r.rank", "<=", CLIENT_REPORTS_SHOWN)
+            .orderBy("r.last_at", "desc")
+            .execute();
+        for (const r of rows) {
+            const list = reports.get(r.plugin) ?? [];
+            list.push({
+                orgId: r.org_id,
+                contribution: r.contribution,
+                kind: r.kind,
+                count: r.count,
+                firstAt: r.first_at.toISOString(),
+                lastAt: r.last_at.toISOString(),
+                lastMessage: r.last_message,
+            });
+            reports.set(r.plugin, list);
+        }
+        return { clients, reports };
+    }
 };
 __decorate([
     Transactional()

package/dist/extensions/blobs.d.ts

@@ -1,3 +1,4 @@
+import { ClientBuilds } from "../client/client-builds.service.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -10,6 +11,13 @@ import type { ExtensionPackage } from "./package.js";
  *   extension, F-Q): PG `extension_blobs` (`blob_store = pg`, also limited by `packages.maxBytes`).
  * Each package's location is recorded in `extension_packages.blob_store`; reads follow the record and
  * check the sha256.
+ *
+ * A package with an `extension.client` section also stores its client build (`ClientBuilds`,
+ * client extensions spec §9.1): the client files are read again from the bytes being stored,
+ * checked against the section and written to object storage before the package row's transaction,
+ * and the build row is inserted in that transaction, all under the build's lock. Without object
+ * storage (`ClientBuilds`' own, which the CLI points at its store) such a package is refused
+ * (`storage.unavailable`), so a stored build always has its files.
  */
 /** 取到的包与 sha256 不符（存储里的字节被篡改或损坏）。 */
 export declare class ExtensionBlobIntegrityError extends Error {
@@ -31,6 +39,7 @@ export declare class ExtensionBlobs {
     /** Without an object-store extension (the CLI) packages go to PG. */
     private readonly storage;
     private readonly config;
+    private readonly clientBuilds;
     /**
      * CLI only: packages the CLI process imported itself and reads back before the store, since such
      * a package may be recorded in an object store the CLI cannot read. Each entry's sha256 was
@@ -40,7 +49,7 @@ export declare class ExtensionBlobs {
     private readonly local;
     constructor(db: KernelDb, txHost: TransactionHost, 
     /** Without an object-store extension (the CLI) packages go to PG. */
-    storage: StorageService, config: KernelConfigService);
+    storage: StorageService, config: KernelConfigService, clientBuilds: ClientBuilds);
     /** `packages.maxBytes` (read at every call). */
     private maxBytes;
     /**
@@ -54,6 +63,10 @@ export declare class ExtensionBlobs {
      * (content-addressed, idempotent; replicas writing the same package concurrently is harmless).
      */
     put(p: ExtensionPackage, bytes: Uint8Array, src: ExtensionBlobSource): Promise<void>;
+    /** {@link put} after its checks; `client` for a package with client code (under its lock). */
+    private store;
+    /** The files under `dist/client/` of a package's bytes (sha256 already checked by the caller). */
+    private clientFiles;
     private record;
     /** 已有记录的包：按记录的存放位置检查字节在不在，不在就写回（调用方已校验 sha256）。 */
     private repair;