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

package/dist/ui/views.js

@@ -20,7 +20,7 @@ import { readUiArrangement } from "../identity/settings.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
-import { arrange, arrangeBySlot, effectiveEntry, ORG_ARRANGEABLE, orderItems, } from "./arrangement.js";
+import { arrange, arrangeBySlot, effectiveEntry, isSingle, keyOf, ORG_ARRANGEABLE, orderItems, resolveSingleSlot, storedUse, } from "./arrangement.js";
 import { callExtension } from "./call-extension.js";
 import { canUseSlot, UUID_RE } from "./registry.js";
 export { callExtension } from "./call-extension.js";
@@ -73,12 +73,14 @@ export function dropForeignOpens(view, panels) {
     return { ...rest, ...(open !== undefined && ok(open) && { open }), blocks };
 }
 /**
- * Lists contributions for a listing route: no alias, a view's render registered; base order
- * (spec §5): extension name, then manifest order (stable).
+ * Lists contributions for a listing route: no alias, a view's render registered (an embed or a
+ * component is listed without one: a component's server view is optional); base order (spec §5):
+ * extension name, then manifest order (stable).
  */
 function listed(entries) {
     return entries
-        .filter((c) => c.contribution.aliasOf === undefined && (c.contribution.kind === "embed" || c.render))
+        .filter((c) => c.contribution.aliasOf === undefined &&
+        (c.contribution.kind === "embed" || c.contribution.kind === "component" || c.render))
         .map((c, i) => ({ c, i }))
         .sort((x, y) => (x.c.plugin === y.c.plugin ? x.i - y.i : x.c.plugin < y.c.plugin ? -1 : 1))
         .map(({ c: { plugin, contribution: c, slot: s, after } }) => ({
@@ -92,6 +94,8 @@ function listed(entries) {
         icon: c.icon ?? "puzzle",
     }));
 }
+/** The candidates of a single slot in an arrangement listing. */
+const candidatesOf = (items) => items.map((i) => ({ key: keyOf(i), title: i.title }));
 /** The items in effective order, each marked hidden or not (hidden ones stay in place). */
 function withHidden(items, entry) {
     const hidden = new Set(entry.hidden);
@@ -107,12 +111,15 @@ const TOAST_MAX = 500;
 const MAX_LOGGED_PROBLEMS = 10;
 const notFound = () => new ApiError("ui.not_found", "UI contribution not found");
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-/** 校验动作结果，返回问题列表（空 = 合法）。 */
-function actionResultProblems(r) {
+/**
+ * 校验动作结果，返回问题列表（空 = 合法）。A new `view` may carry `data` only for a component
+ * (`component`).
+ */
+function actionResultProblems(r, component) {
     if (!isObj(r))
         return ["action result must be an object"];
     if (r.view !== undefined)
-        return validateUiView(r.view).map((p) => `view: ${p}`);
+        return validateUiView(r.view, { component }).map((p) => `view: ${p}`);
     if (r.toast === undefined)
         return [];
     if (!isObj(r.toast))
@@ -133,6 +140,8 @@ function actionResultProblems(r) {
  *   org; org: the role alone); refused is 404 `ui.not_found`, the same as not existing;
  * - a view takes only the context id of its scope (`conversationId` / `agentId`): a missing one or
  *   one of another scope is 400 `validation_failed`;
+ * - a component's server view (`ctx.ui.view(<component id>)`) is served like a view of its slot;
+ *   only its views carry `data` (a plain view's `data` is 502 `ui.invalid_view`);
  * - 调用带 5 秒时限与中止信号：render 抛错 502 `ui.render_failed`、action 抛错 502 `ui.action_failed`、
  *   超时 504 `ui.timeout`、返回非法视图 502
  *   `ui.invalid_view`，都记告警日志、不写对话日志（这些不是模型可见的内容）。
@@ -160,9 +169,15 @@ let UiViews = class UiViews {
     }
     /**
      * The contributions the role may use in the org, of one slot or of every org-reachable slot:
-     * the extension enabled and loaded, a view's render registered, the slot's `minRole`
-     * ({@link canUseSlot}, so never `platform.page`); no alias, no `file.preview` contribution (the
-     * file previewers list those). Base order (spec §5): extension name, then manifest order.
+     * the extension enabled and loaded, a view's render registered (a component is listed with or
+     * without a server view), the slot's `minRole` ({@link canUseSlot}, so never `platform.page`);
+     * no alias, no `file.preview` contribution (the file previewers list those). Base order (spec
+     * §5): extension name, then manifest order. A single slot lists at most its winner
+     * ({@link resolveSingleSlot} over what this role may use: none until one is chosen, and the web
+     * renders the built-in); display only, the routes that serve a contribution never read it. The
+     * winner is listed whether or not its client code may load (kill switch, per-plugin disable,
+     * client API support): the web renders the built-in when the org's client set has no such
+     * component, and any other consumer must do the same.
      */
     async contributions(orgId, role, slot) {
         const items = await this.orgBase(orgId, role, slot);
@@ -172,7 +187,16 @@ let UiViews = class UiViews {
             this.d.orgArrangement(orgId),
             this.d.platformArrangement(),
         ]);
-        return arrangeBySlot(items, (s) => effectiveEntry(org, platform, s).entry);
+        const winners = new Map();
+        const winnerOf = (s) => {
+            if (!winners.has(s)) {
+                const available = new Set(items.filter((i) => i.slot === s).map(keyOf));
+                winners.set(s, resolveSingleSlot(s, org?.[s], platform[s], available));
+            }
+            return winners.get(s) ?? null;
+        };
+        const shown = items.filter((i) => !isSingle(i.slot) || keyOf(i) === winnerOf(i.slot));
+        return arrangeBySlot(shown, (s) => effectiveEntry(org, platform, s).entry);
     }
     /** {@link contributions} before the arrangement: what the role may use, in base order. */
     async orgBase(orgId, role, slot) {
@@ -187,7 +211,8 @@ let UiViews = class UiViews {
     }
     /**
      * The arrangement page of an org: every org-arrangeable slot with the contributions the role may
-     * use, in effective order with the hidden ones in place, and where the entry comes from.
+     * use: a list slot in effective order with the hidden ones in place, and where the entry comes
+     * from; a single slot with its candidates, the stored `use` and whether it follows the platform.
      */
     async arrangementView(orgId, role) {
         // the page is for people who arrange or at least see the org's UI, not for a guest
@@ -199,17 +224,18 @@ let UiViews = class UiViews {
             this.d.platformArrangement(),
         ]);
         return ORG_ARRANGEABLE.map((slot) => {
+            const items = base.filter((i) => i.slot === slot);
+            if (isSingle(slot)) {
+                return { slot, candidates: candidatesOf(items), ...storedUse(org, platform, slot) };
+            }
             const { entry, source } = effectiveEntry(org, platform, slot);
-            return {
-                slot,
-                source,
-                items: withHidden(base.filter((i) => i.slot === slot), entry),
-            };
+            return { slot, source, items: withHidden(items, entry) };
         });
     }
     /**
      * The platform's arrangement page: every arrangeable slot with the contributions of every running
-     * extension (whatever its org enablement), ordered by the platform entry, hidden ones in place.
+     * extension (whatever its org enablement): a list slot ordered by the platform entry, hidden ones
+     * in place; a single slot with its candidates and the platform's `use`.
      */
     async platformArrangementView() {
         const [base, platform] = await Promise.all([
@@ -217,18 +243,19 @@ let UiViews = class UiViews {
             this.d.platformArrangement(),
         ]);
         return UI_ARRANGEABLE_SLOTS.map((slot) => {
+            const items = base.filter((i) => i.slot === slot);
+            if (isSingle(slot)) {
+                const { use } = storedUse(undefined, platform, slot);
+                return { slot, candidates: candidatesOf(items), use, followsPlatform: false };
+            }
             const { entry, source } = effectiveEntry(undefined, platform, slot);
-            return {
-                slot,
-                source,
-                items: withHidden(base.filter((i) => i.slot === slot), entry),
-            };
+            return { slot, source, items: withHidden(items, entry) };
         });
     }
     /**
      * The `platform.page` contributions of the running extensions, for the admin console (super
-     * admins; no org enablement applies): no alias, a view's render registered. Base order like
-     * {@link contributions}.
+     * admins; no org enablement applies): no alias, a view's render registered (a component is
+     * listed with or without a server view). Base order like {@link contributions}.
      */
     async platformContributions() {
         const items = listed(this.d.host.uiContributions().filter((c) => c.slot.id === "platform.page"));
@@ -289,7 +316,8 @@ let UiViews = class UiViews {
         const { entry, args } = await this.resolve(t, "render");
         const render = entry.render;
         const view = await this.call(t, "render", (signal) => render({ ...args, signal }));
-        this.check(t, "render", validateUiView(view));
+        // `data` only from a component's view (client extensions spec §5.2)
+        this.check(t, "render", validateUiView(view, { component: entry.contribution.kind === "component" }));
         return dropForeignOpens(view, this.panels(t.plugin));
     }
     /** 执行动作：调用插件 `action`（视图里的按钮 / 表单提交），校验返回的提示或新视图。 */
@@ -303,7 +331,7 @@ let UiViews = class UiViews {
             ...(input.payload !== undefined && { payload: input.payload }),
             ...(input.answer !== undefined && { answer: input.answer }),
         }));
-        this.check(t, "action", actionResultProblems(r));
+        this.check(t, "action", actionResultProblems(r, entry.contribution.kind === "component"));
         const res = r;
         if (res.view !== undefined)
             return { view: dropForeignOpens(res.view, this.panels(t.plugin)) };
@@ -338,7 +366,9 @@ let UiViews = class UiViews {
             c.contribution.aliasOf === undefined &&
             (need === "embed"
                 ? c.contribution.kind === "embed"
-                : c.contribution.kind === "view" && c[need] !== undefined));
+                : // a view, or a component's server view (served like a view of its slot)
+                    (c.contribution.kind === "view" || c.contribution.kind === "component") &&
+                        c[need] !== undefined));
         if (t.scope === "platform") {
             const found = platformEntry(entry);
             return { entry: found, args: this.platformArgs(t, found) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.14",
+  "version": "0.1.0-rc.16",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -65,7 +65,7 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.10"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.12"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
@@ -74,7 +74,7 @@
     "@types/ws": "^8.18.2",
     "@types/yauzl": "3.4.0",
     "ws": "^8.22.0",
-    "@capybara-hq/testing": "0.1.0-rc.13"
+    "@capybara-hq/testing": "0.1.0-rc.15"
   },
   "scripts": {
     "build": "tsc -b"

package/src/migrations/0107_extension_client_builds.sql

@@ -0,0 +1,50 @@
+-- Client extensions (spec 2026-11-09-client-extensions-design.md §9.1, §10.4).
+-- extension_client_builds: the client files of an extension package, keyed by the package sha256
+-- (the build id). The files live in object storage under `deployment/<object_prefix>`; the
+-- integrity values delivered to browsers come from this row, never from the object store.
+CREATE TABLE IF NOT EXISTS extension_client_builds (
+  package_sha256 text PRIMARY KEY REFERENCES extension_packages(sha256) ON DELETE CASCADE,
+  plugin text NOT NULL,
+  entry text,
+  styles text[] NOT NULL,
+  assets text[] NOT NULL,
+  integrity jsonb NOT NULL,
+  sizes jsonb NOT NULL,
+  api_version int NOT NULL,
+  object_prefix text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- extension_client_reports: crash and load reports of client code, one row per
+-- (plugin, build, org, contribution, kind); org_id is null for admin pages. Upserted, pruned after
+-- 30 days.
+CREATE TABLE IF NOT EXISTS extension_client_reports (
+  plugin text NOT NULL,
+  build text NOT NULL,
+  org_id text NULL,
+  contribution text NULL,
+  kind text NOT NULL CHECK (kind IN ('load', 'render', 'event', 'api', 'budget')),
+  count int NOT NULL DEFAULT 1,
+  first_at timestamptz NOT NULL DEFAULT now(),
+  last_at timestamptz NOT NULL DEFAULT now(),
+  last_message text NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS extension_client_reports_key_uq
+  ON extension_client_reports (
+    plugin, build, (coalesce(org_id, '')), (coalesce(contribution, '')), kind
+  );
+
+CREATE INDEX IF NOT EXISTS extension_client_reports_last_at
+  ON extension_client_reports (last_at);
+
+-- extension_replica_status.serving_sha256: the package a replica actually serves for the plugin
+-- (the row's own sha256 when loaded; the older package still running when the row's version is
+-- pending approval or failed; null when none runs). Client code follows the server code that runs
+-- (spec §9.3): a build is delivered while a live replica serves its package.
+ALTER TABLE extension_replica_status ADD COLUMN IF NOT EXISTS serving_sha256 text NULL;
+
+-- catalog_item_versions.appearance_order: the keys of plugin.json's
+-- suggestedAppearance.replacements in the author's order (a jsonb object does not keep key order),
+-- so the suggestion is listed and applied in that order (spec §6.5); null without replacements.
+ALTER TABLE catalog_item_versions ADD COLUMN IF NOT EXISTS appearance_order text[] NULL;