@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/ui/embed-token.js

@@ -24,10 +24,12 @@ const B64URL = /^[A-Za-z0-9_-]+$/;
 const PLUGIN_RE = /^[a-z][a-z0-9-]{1,40}$/;
 const CLAIM_KEYS = new Set([
     "plugin",
+    "scope",
     "orgId",
     "accountId",
     "role",
     "conversationId",
+    "agentId",
     "fileId",
     "contribution",
     "exp",
@@ -44,7 +46,11 @@ function decodeStrict(s) {
     const buf = Buffer.from(s, "base64url");
     return buf.toString("base64url") === s ? buf : null;
 }
-/** 逐字段核对声明：只认已知字段、类型正确，返回只含已知字段的新对象。 */
+/**
+ * 逐字段核对声明：只认已知字段、类型正确，返回只含已知字段的新对象。The scope decides the shape:
+ * `"platform"` exactly when `orgId` is absent and `role` is `"superAdmin"`, with no
+ * `conversationId` / `agentId` / `fileId`; `"org"` needs an `orgId` and one of the org roles.
+ */
 function parseClaims(v) {
     if (typeof v !== "object" || v === null || Array.isArray(v))
         return null;
@@ -53,22 +59,41 @@ function parseClaims(v) {
         return null;
     if (typeof c.plugin !== "string" || !PLUGIN_RE.test(c.plugin))
         return null;
-    if (!isId(c.orgId) || !isId(c.accountId) || !isId(c.contribution))
+    if (!isId(c.accountId) || !isId(c.contribution))
         return null;
-    if (!ROLES.has(c.role))
+    if (typeof c.exp !== "number" || !Number.isSafeInteger(c.exp))
+        return null;
+    if (c.scope === "platform") {
+        if (c.orgId !== undefined || c.role !== "superAdmin")
+            return null;
+        if (c.conversationId !== undefined || c.agentId !== undefined || c.fileId !== undefined) {
+            return null;
+        }
+        return {
+            plugin: c.plugin,
+            scope: "platform",
+            accountId: c.accountId,
+            role: "superAdmin",
+            contribution: c.contribution,
+            exp: c.exp,
+        };
+    }
+    if (c.scope !== "org" || !isId(c.orgId) || !ROLES.has(c.role))
         return null;
     if (c.conversationId !== undefined && !isId(c.conversationId))
         return null;
-    if (c.fileId !== undefined && (!isId(c.fileId) || c.conversationId === undefined))
+    if (c.agentId !== undefined && (!isId(c.agentId) || c.conversationId !== undefined))
         return null;
-    if (typeof c.exp !== "number" || !Number.isSafeInteger(c.exp))
+    if (c.fileId !== undefined && (!isId(c.fileId) || c.conversationId === undefined))
         return null;
     return {
         plugin: c.plugin,
+        scope: "org",
         orgId: c.orgId,
         accountId: c.accountId,
         role: c.role,
         ...(c.conversationId !== undefined && { conversationId: c.conversationId }),
+        ...(c.agentId !== undefined && { agentId: c.agentId }),
         ...(c.fileId !== undefined && { fileId: c.fileId }),
         contribution: c.contribution,
         exp: c.exp,

package/dist/ui/registry.d.ts

@@ -1,13 +1,13 @@
-import type { ExtensionManifest, UiActionArgs, UiActionResult, UiContribution, UiRenderArgs, UiView } from "@capybara-hq/plugin-sdk";
+import type { ExtensionManifest, UiActionArgs, UiActionResult, UiRenderArgs, UiSlotSpec, UiView } from "@capybara-hq/plugin-sdk";
 import { type OrgRole } from "../orgs/roles.js";
 /** 会话 id 的格式（UUID）。 */
 export declare const UUID_RE: RegExp;
-/** 组织页面（`place: "page"`）所需的最低角色（A38）：guest 只用对话位置的贡献。 */
-export declare const PAGE_MIN_ROLE: OrgRole;
-/** Places on the conversation page (everything but an org page): they need a `conversationId`. */
-export declare const isConversationPlace: (place: UiContribution["place"]) => boolean;
-/** 该角色能否使用这个位置的贡献。 */
-export declare const canUsePlace: (place: UiContribution["place"], role: OrgRole) => boolean;
+/**
+ * Whether an org role may use contributions in this slot (UI slots spec §7): never a `superAdmin`
+ * slot (`platform.page` is served only by the org-less platform routes), else the slot's
+ * `minRole`. The slot's scope rule (conversation, agent, file) is checked after this.
+ */
+export declare function canUseSlot(slot: UiSlotSpec, role: OrgRole): boolean;
 /** 插件视图的 render 函数（`ctx.ui.view` 注册）。 */
 export type UiRender = (args: UiRenderArgs) => Promise<UiView>;
 /** 插件视图的动作处理函数（`ctx.ui.action` 注册）。 */
@@ -17,7 +17,22 @@ export type UiActionHandler = (args: UiActionArgs) => Promise<UiActionResult>;
  * 对话视图的刷新走会话主题 `conv.<id>`（与事件、增量共用），见 `conversationTopic`。
  */
 export declare const orgUiTopic: (orgId: string) => string;
-/** 界面刷新消息：`conv.<id>` 与 `org-ui.<orgId>` 上的 `{ kind: "ui", plugin, contribution }`。 */
+/**
+ * The kernel bus topic of the platform refresh (namespace `kernel`): `ctx.ui.invalidate` of a
+ * `platform.page` contribution (no `orgId`), read by `GET /api/v1/admin/ui/stream`.
+ */
+export declare const PLATFORM_UI_TOPIC = "platform-ui";
+/** A checked `ui.invalidate` target: an org's (optionally one conversation's) or the platform's. */
+export type UiInvalidateTarget = {
+    scope: "org";
+    orgId: string;
+    conversationId?: string;
+    contribution: string;
+} | {
+    scope: "platform";
+    contribution: string;
+};
+/** 界面刷新消息：`conv.<id>`、`org-ui.<orgId>` 与 `platform-ui` 上的 `{ kind: "ui", plugin, contribution }`。 */
 export interface UiBusMessage {
     kind: "ui";
     plugin: string;
@@ -30,29 +45,39 @@ export declare const uiFrame: (m: UiBusMessage) => string;
 /**
  * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
  * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
- * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ * The id must be in `permissions.ui.views` or `permissions.ui.components` (a component's server
+ * view, client extensions spec §5.2); `defineExtension` already cross-checked them with the
+ * manifest `ui`.
  */
 export declare class PluginUiRegistration {
     private readonly manifest;
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     private readonly deny;
     readonly views: Map<string, UiRender>;
     readonly actions: Map<string, UiActionHandler>;
     private readonly declaredViews;
     private readonly contributions;
+    /** The ids of the manifest's `component` contributions: their permission is `ui.components`. */
+    private readonly components;
     private sealed;
     constructor(manifest: ExtensionManifest, 
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     deny: (item: string) => never);
     /** setup 结束后调用：此后 view / action 抛错。 */
     seal(): void;
     view(id: string, render: UiRender): void;
     action(id: string, handler: UiActionHandler): void;
-    /** 校验 invalidate 的目标，返回规范化后的 `{ orgId, conversationId?, contribution }`。 */
-    target(t: unknown): {
-        orgId: string;
-        conversationId?: string;
-        contribution: string;
-    };
+    /**
+     * 校验 invalidate 的目标。A contribution in `platform` (the ids of the extension's `platform.page`
+     * contributions) takes no `orgId` and no `conversationId`; every other contribution needs an
+     * `orgId`.
+     */
+    target(t: unknown, platform: ReadonlySet<string>): UiInvalidateTarget;
     private register;
 }

package/dist/ui/registry.js

@@ -1,17 +1,24 @@
 import { roleAtLeast } from "../orgs/roles.js";
 /** 会话 id 的格式（UUID）。 */
 export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/** 组织页面（`place: "page"`）所需的最低角色（A38）：guest 只用对话位置的贡献。 */
-export const PAGE_MIN_ROLE = "member";
-/** Places on the conversation page (everything but an org page): they need a `conversationId`. */
-export const isConversationPlace = (place) => place !== "page";
-/** 该角色能否使用这个位置的贡献。 */
-export const canUsePlace = (place, role) => place !== "page" || roleAtLeast(role, PAGE_MIN_ROLE);
+/**
+ * Whether an org role may use contributions in this slot (UI slots spec §7): never a `superAdmin`
+ * slot (`platform.page` is served only by the org-less platform routes), else the slot's
+ * `minRole`. The slot's scope rule (conversation, agent, file) is checked after this.
+ */
+export function canUseSlot(slot, role) {
+    return slot.minRole !== "superAdmin" && roleAtLeast(role, slot.minRole);
+}
 /**
  * 组织级界面刷新的内核 bus 主题（命名空间 `kernel`）：`org-ui.<orgId>`。
  * 对话视图的刷新走会话主题 `conv.<id>`（与事件、增量共用），见 `conversationTopic`。
  */
 export const orgUiTopic = (orgId) => `org-ui.${orgId}`;
+/**
+ * The kernel bus topic of the platform refresh (namespace `kernel`): `ctx.ui.invalidate` of a
+ * `platform.page` contribution (no `orgId`), read by `GET /api/v1/admin/ui/stream`.
+ */
+export const PLATFORM_UI_TOPIC = "platform-ui";
 /** 是否为界面刷新消息（bus 上的消息来自其他副本，按形状核对）。 */
 export function isUiBusMessage(m) {
     if (typeof m !== "object" || m === null)
@@ -24,7 +31,9 @@ export const uiFrame = (m) => `event: ui\ndata: ${JSON.stringify({ plugin: m.plu
 /**
  * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
  * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
- * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ * The id must be in `permissions.ui.views` or `permissions.ui.components` (a component's server
+ * view, client extensions spec §5.2); `defineExtension` already cross-checked them with the
+ * manifest `ui`.
  */
 export class PluginUiRegistration {
     manifest;
@@ -33,14 +42,21 @@ export class PluginUiRegistration {
     actions = new Map();
     declaredViews;
     contributions;
+    /** The ids of the manifest's `component` contributions: their permission is `ui.components`. */
+    components;
     sealed = false;
     constructor(manifest, 
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     deny) {
         this.manifest = manifest;
         this.deny = deny;
-        this.declaredViews = new Set(manifest.permissions?.ui?.views ?? []);
+        const ui = manifest.permissions?.ui;
+        this.declaredViews = new Set([...(ui?.views ?? []), ...(ui?.components ?? [])]);
         this.contributions = new Set((manifest.ui ?? []).map((c) => c.id));
+        this.components = new Set((manifest.ui ?? []).filter((c) => c.kind === "component").map((c) => c.id));
     }
     /** setup 结束后调用：此后 view / action 抛错。 */
     seal() {
@@ -52,13 +68,15 @@ export class PluginUiRegistration {
     action(id, handler) {
         this.register("action", this.actions, id, handler);
     }
-    /** 校验 invalidate 的目标，返回规范化后的 `{ orgId, conversationId?, contribution }`。 */
-    target(t) {
+    /**
+     * 校验 invalidate 的目标。A contribution in `platform` (the ids of the extension's `platform.page`
+     * contributions) takes no `orgId` and no `conversationId`; every other contribution needs an
+     * `orgId`.
+     */
+    target(t, platform) {
         const name = this.manifest.name;
         const x = (typeof t === "object" && t !== null ? t : {});
         const id = (v) => typeof v === "string" && v !== "" && v.length <= 200;
-        if (!id(x.orgId))
-            throw new Error(`plugin ${name}: ui.invalidate needs a non-empty orgId`);
         if (x.conversationId !== undefined &&
             (typeof x.conversationId !== "string" || !UUID_RE.test(x.conversationId))) {
             throw new Error(`plugin ${name}: ui.invalidate conversationId must be a UUID`);
@@ -66,7 +84,19 @@ export class PluginUiRegistration {
         if (typeof x.contribution !== "string" || !this.contributions.has(x.contribution)) {
             throw new Error(`plugin ${name}: ui.invalidate: ${JSON.stringify(x.contribution)} is not a ui contribution in the manifest`);
         }
+        if (platform.has(x.contribution)) {
+            if (x.orgId !== undefined) {
+                throw new Error(`plugin ${name}: ui.invalidate: ${x.contribution} is a platform page; omit orgId`);
+            }
+            if (x.conversationId !== undefined) {
+                throw new Error(`plugin ${name}: ui.invalidate: ${x.contribution} is a platform page; omit conversationId`);
+            }
+            return { scope: "platform", contribution: x.contribution };
+        }
+        if (!id(x.orgId))
+            throw new Error(`plugin ${name}: ui.invalidate needs a non-empty orgId`);
         return {
+            scope: "org",
             orgId: x.orgId,
             ...(x.conversationId !== undefined && { conversationId: x.conversationId }),
             contribution: x.contribution,
@@ -78,7 +108,9 @@ export class PluginUiRegistration {
             throw new Error(`plugin ${name}: ui.${what} is only allowed during setup; setup has completed`);
         }
         if (typeof id !== "string" || !this.declaredViews.has(id)) {
-            this.deny(`permissions.ui.views ${String(id)}`);
+            // name the list the id belongs in: a component's server view is declared under components
+            const list = typeof id === "string" && this.components.has(id) ? "components" : "views";
+            this.deny(`permissions.ui.${list} ${String(id)}`);
         }
         if (typeof fn !== "function") {
             throw new Error(`plugin ${name}: ui.${what} "${id}" handler must be a function`);

package/dist/ui/slots.controller.d.ts

@@ -0,0 +1,11 @@
+import { type UiSlotSpec } from "@capybara-hq/plugin-sdk";
+/**
+ * The slot catalog (UI slots spec §3): every slot an extension can contribute to, verbatim from
+ * the SDK. Static, so any signed-in person may read it; no org is involved.
+ */
+export declare class SlotsController {
+    /** `GET /api/v1/ui/slots` → `{ slots }`. */
+    slots(): {
+        slots: readonly UiSlotSpec[];
+    };
+}

package/dist/ui/slots.controller.js

@@ -0,0 +1,25 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { UI_SLOTS } from "@capybara-hq/plugin-sdk";
+import { Controller, Get } from "@nestjs/common";
+/**
+ * The slot catalog (UI slots spec §3): every slot an extension can contribute to, verbatim from
+ * the SDK. Static, so any signed-in person may read it; no org is involved.
+ */
+let SlotsController = class SlotsController {
+    /** `GET /api/v1/ui/slots` → `{ slots }`. */
+    slots() {
+        return { slots: UI_SLOTS };
+    }
+};
+__decorate([
+    Get("slots")
+], SlotsController.prototype, "slots", null);
+SlotsController = __decorate([
+    Controller("api/v1/ui")
+], SlotsController);
+export { SlotsController };

package/dist/ui/ui-stream.d.ts

@@ -6,20 +6,37 @@ import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.j
 import { type OrgRole } from "../orgs/roles.js";
 import { type SseOutput, type StreamBus, type StreamHandle } from "../runtime/stream.js";
 export interface OrgUiStreamParams {
+    scope?: "org";
     orgId: string;
     viewerAccountId: string;
     credential: CredentialCheck;
 }
+/** The platform refresh stream (`GET /api/v1/admin/ui/stream`): a super admin's, no org. */
+export interface PlatformUiStreamParams {
+    scope: "platform";
+    viewerAccountId: string;
+    credential: CredentialCheck;
+}
+export type UiStreamParams = OrgUiStreamParams | PlatformUiStreamParams;
 /** The org role the org UI stream re-checks. */
 export declare class UiStreamMembership {
     private readonly db;
     constructor(db: KernelDb);
     /** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
     role(orgId: string, accountId: string): Promise<OrgRole | undefined>;
+    /** Whether the account is an active super admin (one query). */
+    superAdmin(accountId: string): Promise<boolean>;
 }
+/**
+ * The org refresh stream is member and above (UI slots spec §7): it carries `org.page` and
+ * `org.settings.section` refreshes; an `agent.detail.section` a guest views refreshes on navigation.
+ */
+export declare const ORG_STREAM_MIN_ROLE: OrgRole;
 /**
  * 组织级界面刷新流（SSE）：订阅内核主题 `org-ui.<orgId>`，把插件 `ctx.ui.invalidate`（不带对话）的刷新
- * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
+ * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。The platform variant subscribes
+ * `platform-ui` (`invalidate` of a `platform.page`, no org) for a super admin, re-checked on the
+ * same interval (losing super admin ends it with `event: error`, code `forbidden`).跨副本只经 Redis bus；进程内只持有连接本身的资源
  * （订阅、心跳与复核定时器），停机时一并关闭。
  */
 export declare class OrgUiStreams {
@@ -33,9 +50,9 @@ export declare class OrgUiStreams {
      * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
      * streams end with their connections.
      */
-    constructor(bus: StreamBus, membership: Pick<UiStreamMembership, "role">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn">, shutdown?: Pick<GracefulShutdown, "signal">);
+    constructor(bus: StreamBus, membership: Pick<UiStreamMembership, "role" | "superAdmin">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn">, shutdown?: Pick<GracefulShutdown, "signal">);
     /** 复核凭据与成员关系并订阅；失败时尚未写响应，调用方按普通错误返回。 */
-    open(p: OrgUiStreamParams, out: SseOutput): Promise<StreamHandle>;
+    open(p: UiStreamParams, out: SseOutput): Promise<StreamHandle>;
     /** Closes every stream of this process (at shutdown) and latches, like `ConversationStreams`. */
     closeAll(): void;
     get size(): number;

package/dist/ui/ui-stream.js

@@ -8,6 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Inject, Injectable, Optional } from "@nestjs/common";
+import { currentPlatformAccount } from "../ctx/create-ctx.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -15,7 +16,9 @@ import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.j
 import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { roleAtLeast } from "../orgs/roles.js";
 import { endedStream, } from "../runtime/stream.js";
-import { isUiBusMessage, orgUiTopic, PAGE_MIN_ROLE, uiFrame } from "./registry.js";
+import { isUiBusMessage, orgUiTopic, PLATFORM_UI_TOPIC, uiFrame } from "./registry.js";
+/** The log field naming the stream: its org, or the platform scope. */
+const whereOf = (p) => p.scope === "platform" ? { scope: "platform" } : { orgId: p.orgId };
 /** The org role the org UI stream re-checks. */
 let UiStreamMembership = class UiStreamMembership {
     db;
@@ -36,26 +39,39 @@ let UiStreamMembership = class UiStreamMembership {
             .executeTakeFirst();
         return row?.role;
     }
+    /** Whether the account is an active super admin (one query). */
+    superAdmin(accountId) {
+        return currentPlatformAccount(this.db.db, accountId);
+    }
 };
 UiStreamMembership = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb))
 ], UiStreamMembership);
 export { UiStreamMembership };
+/**
+ * The org refresh stream is member and above (UI slots spec §7): it carries `org.page` and
+ * `org.settings.section` refreshes; an `agent.detail.section` a guest views refreshes on navigation.
+ */
+export const ORG_STREAM_MIN_ROLE = "member";
 async function authorize(d, p) {
     const denied = await p.credential();
     if (denied !== null)
         return denied;
+    if (p.scope === "platform")
+        return (await d.superAdmin(p.viewerAccountId)) ? null : "forbidden";
     const role = await d.memberRole(p.orgId, p.viewerAccountId);
     if (role === undefined)
         return "org.not_found";
-    return roleAtLeast(role, PAGE_MIN_ROLE) ? null : "ui.not_found";
+    return roleAtLeast(role, ORG_STREAM_MIN_ROLE) ? null : "ui.not_found";
 }
 /** 慢客户端的积压上限（刷新帧很小，超过即说明客户端不读了）。 */
 const MAX_BACKLOG_BYTES = 1024 * 1024;
 /**
  * 组织级界面刷新流（SSE）：订阅内核主题 `org-ui.<orgId>`，把插件 `ctx.ui.invalidate`（不带对话）的刷新
- * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
+ * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。The platform variant subscribes
+ * `platform-ui` (`invalidate` of a `platform.page`, no org) for a super admin, re-checked on the
+ * same interval (losing super admin ends it with `event: error`, code `forbidden`).跨副本只经 Redis bus；进程内只持有连接本身的资源
  * （订阅、心跳与复核定时器），停机时一并关闭。
  */
 let OrgUiStreams = class OrgUiStreams {
@@ -73,6 +89,7 @@ let OrgUiStreams = class OrgUiStreams {
         this.d = {
             bus,
             memberRole: (orgId, accountId) => membership.role(orgId, accountId),
+            superAdmin: (accountId) => membership.superAdmin(accountId),
             config,
             log,
         };
@@ -140,7 +157,8 @@ class OrgUiConnection {
         this.onClosed = onClosed;
     }
     async subscribe() {
-        const un = await this.d.bus.subscribe(orgUiTopic(this.p.orgId), (m) => {
+        const topic = this.p.scope === "platform" ? PLATFORM_UI_TOPIC : orgUiTopic(this.p.orgId);
+        const un = await this.d.bus.subscribe(topic, (m) => {
             // begin() 之前（响应头还没写）到达的刷新丢掉：网页连上后会先取一次视图
             if (this.begun && isUiBusMessage(m))
                 this.write(uiFrame(m));
@@ -166,7 +184,7 @@ class OrgUiConnection {
         this.timers = [];
         const un = this.unsubscribe;
         this.unsubscribe = undefined;
-        un?.().catch((err) => this.d.log.warn("org ui stream unsubscribe failed", { orgId: this.p.orgId, err }));
+        un?.().catch((err) => this.d.log.warn("org ui stream unsubscribe failed", { ...whereOf(this.p), err }));
         if (this.begun) {
             try {
                 if (mode === "abort")
@@ -191,7 +209,7 @@ class OrgUiConnection {
             return;
         }
         if (this.out.backlog() > MAX_BACKLOG_BYTES) {
-            this.d.log.warn("org ui stream client too slow; closing", { orgId: this.p.orgId });
+            this.d.log.warn("org ui stream client too slow; closing", whereOf(this.p));
             this.close("abort");
         }
     }
@@ -206,7 +224,7 @@ class OrgUiConnection {
         }
         catch (err) {
             this.d.log.warn("org ui stream access re-check failed; closing", {
-                orgId: this.p.orgId,
+                ...whereOf(this.p),
                 err,
             });
             code = "internal";

package/dist/ui/ui.schemas.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** The contribution named in a view / action / embed path (`:plugin/:id`). */
+export declare const ContributionParams: z.ZodObject<{
+    plugin: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+/** `GET contributions?slot=`: one catalog slot, or every org-reachable slot when omitted. */
+export declare const ContributionsQuery: z.ZodObject<{
+    slot: z.ZodOptional<z.ZodEnum<{
+        "agent.detail.section": "agent.detail.section";
+        "conversation.composer.frame": "conversation.composer.frame";
+        "conversation.empty": "conversation.empty";
+        "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";
+        "shell.brand": "shell.brand";
+        "shell.overlay": "shell.overlay";
+    }>>;
+}, z.core.$strip>;
+export declare const ViewQuery: z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodUUID>;
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+    item: z.ZodOptional<z.ZodString>;
+    callId: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ActionBody: z.ZodObject<{
+    actionId: z.ZodString;
+    payload: z.ZodOptional<z.ZodUnknown>;
+    answer: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+    conversationId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodUUID>;
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+export declare const EmbedTokenBody: z.ZodDefault<z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodUUID>;
+    fileId: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strip>>;
+/** `GET /api/v1/admin/ui/views/:plugin/:id?locale=`: a platform page takes no context id. */
+export declare const PlatformViewQuery: z.ZodObject<{
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+/** `POST /api/v1/admin/ui/actions/:plugin/:id`: an action of a platform page (no context id). */
+export declare const PlatformActionBody: z.ZodObject<{
+    actionId: z.ZodString;
+    payload: z.ZodOptional<z.ZodUnknown>;
+    answer: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+/** The slot catalog route the Platform operation `ui.slots` mirrors (`check:platform-ops` key). */
+export declare const UI_ROUTES: readonly RouteSchemas[];

package/dist/ui/ui.schemas.js

@@ -0,0 +1,65 @@
+import { UI_LIMITS, UI_SLOT_IDS } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas of the org UI routes (`views.controller.ts`). */
+const Locale = z.enum(["zh", "en"]).default("en");
+const Id = z.string().min(1).max(100);
+/** The contribution named in a view / action / embed path (`:plugin/:id`). */
+export const ContributionParams = z.object({ plugin: Id, id: Id });
+/** `GET contributions?slot=`: one catalog slot, or every org-reachable slot when omitted. */
+export const ContributionsQuery = z.object({ slot: z.enum(UI_SLOT_IDS).optional() });
+export const ViewQuery = z
+    .object({
+    conversationId: z.string().min(1).max(100).optional(),
+    /** Only an agent view (`agent.detail.section`). */
+    agentId: z.uuid().optional(),
+    locale: Locale,
+    /** A panel opened from an open target: the item to scroll to. */
+    item: z.string().min(1).max(200).optional(),
+    /** An inline card: the tool call it hangs off, and its `ToolResult.card.key`. */
+    callId: z.string().min(1).max(200).optional(),
+    key: z.string().min(1).max(200).optional(),
+})
+    .refine((q) => q.key === undefined || q.callId !== undefined, {
+    message: "key needs callId",
+});
+/**
+ * 表单答案（plugin-sdk 的 `FormAnswer`）。SDK 的 InputForm 没有单独的字段数 / 选项数上限，
+ * 这里沿用视图的上限：键数与多选数组长度 ≤ `UI_LIMITS.tableRows`，单个文本 ≤ `UI_LIMITS.textChars`。
+ */
+const AnswerText = z.string().max(UI_LIMITS.textChars);
+const FormAnswerSchema = z
+    .record(z.string().max(100), z.union([AnswerText, z.number(), z.boolean(), z.array(AnswerText).max(UI_LIMITS.tableRows)]))
+    .refine((a) => Object.keys(a).length <= UI_LIMITS.tableRows, {
+    message: `answer must have at most ${UI_LIMITS.tableRows} fields`,
+});
+/** 按钮 payload 的 JSON 序列化后 UTF-8 字节数（与 `validateUiView` 对按钮 payload 的上限一致）。 */
+const payloadBytes = (v) => Buffer.byteLength(JSON.stringify(v) ?? "", "utf8");
+export const ActionBody = z.object({
+    actionId: z.string().min(1).max(200),
+    payload: z
+        .unknown()
+        .optional()
+        .refine((v) => v === undefined || payloadBytes(v) <= UI_LIMITS.payloadBytes, {
+        message: `payload must be at most ${UI_LIMITS.payloadBytes} bytes as JSON`,
+    }),
+    answer: FormAnswerSchema.optional(),
+    conversationId: z.string().min(1).max(100).optional(),
+    /** Only an agent view (`agent.detail.section`). */
+    agentId: z.uuid().optional(),
+    locale: Locale,
+});
+export const EmbedTokenBody = z
+    .object({
+    conversationId: z.string().min(1).max(100).optional(),
+    /** Only an agent embed (`agent.detail.section`). */
+    agentId: z.uuid().optional(),
+    /** Only a `file.preview` embed: the file version it previews. */
+    fileId: z.uuid().optional(),
+})
+    .default({});
+/** `GET /api/v1/admin/ui/views/:plugin/:id?locale=`: a platform page takes no context id. */
+export const PlatformViewQuery = z.object({ locale: Locale });
+/** `POST /api/v1/admin/ui/actions/:plugin/:id`: an action of a platform page (no context id). */
+export const PlatformActionBody = ActionBody.omit({ conversationId: true, agentId: true });
+/** The slot catalog route the Platform operation `ui.slots` mirrors (`check:platform-ops` key). */
+export const UI_ROUTES = [{ route: "GET /api/v1/ui/slots" }];