@capybara-hq/plugin-sdk 0.1.0-rc.7 → 0.1.0-rc.9

package/dist/ui-slots.js

@@ -0,0 +1,168 @@
+/** Every slot id of the catalog, in catalog order (UI slots spec §3). */
+export const UI_SLOT_IDS = [
+    "conversation.panel",
+    "conversation.properties.section",
+    "conversation.tool-result.card",
+    "org.page",
+    "file.preview",
+    "agent.detail.section",
+    "org.settings.section",
+    "platform.page",
+];
+const SLOT_DATA = [
+    {
+        id: "conversation.panel",
+        version: 1,
+        owner: "components/conversation/RightArea.tsx",
+        scope: "conversation",
+        accepts: ["view", "embed"],
+        cardinality: "list",
+        minRole: "guest",
+        args: ["conversationId", "item"],
+        density: "regular",
+        icon: "optional",
+        description: {
+            en: "A panel beside the conversation, opened from the right area.",
+            zh: "对话旁的面板，从右侧区域打开。",
+        },
+    },
+    {
+        id: "conversation.properties.section",
+        version: 1,
+        owner: "components/conversation/PropertiesSections.tsx",
+        scope: "conversation",
+        accepts: ["view", "embed"],
+        cardinality: "list",
+        minRole: "guest",
+        args: ["conversationId"],
+        density: "dense",
+        icon: "optional",
+        anchors: ["context", "files", "background"],
+        description: {
+            en: "A section in the conversation properties list.",
+            zh: "对话属性列表中的一个分区。",
+        },
+    },
+    {
+        id: "conversation.tool-result.card",
+        version: 1,
+        owner: "components/conversation/RightArea.tsx",
+        scope: "conversation",
+        accepts: ["view", "embed"],
+        cardinality: "list",
+        minRole: "guest",
+        args: ["conversationId", "card"],
+        density: "regular",
+        icon: "optional",
+        description: {
+            en: "A card a tool result opens in the conversation.",
+            zh: "工具结果在对话中打开的卡片。",
+        },
+    },
+    {
+        id: "org.page",
+        version: 1,
+        owner: "app/(app)/p/[plugin]/[id]/view.tsx",
+        scope: "org",
+        accepts: ["view", "embed"],
+        cardinality: "list",
+        minRole: "member",
+        args: [],
+        density: "regular",
+        icon: "optional",
+        description: {
+            en: "A full page in the organization navigation.",
+            zh: "组织导航中的完整页面。",
+        },
+    },
+    {
+        id: "file.preview",
+        version: 1,
+        owner: "components/conversation/FilePanel.tsx",
+        scope: "file",
+        accepts: ["embed"],
+        cardinality: "list",
+        minRole: "guest",
+        args: ["conversationId", "fileId"],
+        density: "regular",
+        icon: "optional",
+        description: {
+            en: "A previewer for a file of the conversation.",
+            zh: "对话中文件的预览器。",
+        },
+    },
+    {
+        id: "agent.detail.section",
+        version: 1,
+        owner: "components/agent/AgentPage.tsx",
+        scope: "agent",
+        accepts: ["view", "embed"],
+        cardinality: "list",
+        minRole: "guest",
+        args: ["agentId"],
+        density: "regular",
+        icon: "optional",
+        description: {
+            en: "A section on the detail page of an agent.",
+            zh: "智能体详情页中的一个分区。",
+        },
+    },
+    {
+        id: "org.settings.section",
+        version: 1,
+        owner: "app/(app)/settings/organization/view.tsx",
+        scope: "org",
+        accepts: ["view", "embed"],
+        cardinality: "list",
+        minRole: "admin",
+        args: [],
+        density: "regular",
+        icon: "optional",
+        description: {
+            en: "A section on the organization settings page.",
+            zh: "组织设置页中的一个分区。",
+        },
+    },
+    {
+        id: "platform.page",
+        version: 1,
+        owner: "app/(app)/admin/p/[plugin]/[id]/view.tsx",
+        scope: "platform",
+        accepts: ["view", "embed"],
+        cardinality: "list",
+        minRole: "superAdmin",
+        args: [],
+        density: "regular",
+        icon: "optional",
+        description: {
+            en: "A full page in the platform administration.",
+            zh: "平台管理中的完整页面。",
+        },
+    },
+];
+export const UI_SLOTS = SLOT_DATA;
+export function uiSlot(id) {
+    return UI_SLOTS.find((s) => s.id === id);
+}
+const SLOT_REF_RE = /^([a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+)(?:@([1-9][0-9]{0,2}))?$/;
+/** Reads `<id>` or `<id>@<version>` (version 1 when omitted); does not check the catalog. */
+export function parseSlotRef(ref) {
+    const m = SLOT_REF_RE.exec(ref);
+    if (!m)
+        return null;
+    return { id: m[1], version: m[2] === undefined ? 1 : Number(m[2]) };
+}
+/** @deprecated step A of the UI slots spec §4 */
+export const PLACE_SLOTS = {
+    panel: "conversation.panel",
+    conversation: "conversation.panel",
+    section: "conversation.properties.section",
+    inline: "conversation.tool-result.card",
+    page: "org.page",
+    "file-preview": "file.preview",
+};
+export const UI_ARRANGEABLE_SLOTS = UI_SLOT_IDS.filter((id) => id !== "file.preview");
+export const UI_CONTRIBUTION_KEY_RE = /^[a-z][a-z0-9-]{1,40}\/[a-z][a-z0-9-]{0,39}$/;
+export function uiContributionKey(plugin, id) {
+    return `${plugin}/${id}`;
+}

package/dist/ui.d.ts

@@ -1,18 +1,13 @@
 import type { Locale } from "./cards.js";
 import { type FormAnswer, type InputForm } from "./tool.js";
+import type { UiSlotId, UiSlotScope } from "./ui-slots.js";
 /**
- * Where a ui contribution goes (UI refresh spec §5.3):
- * - `panel`: a right panel of the conversation page, opened from the extension's icon in the title
- *   bar (one at a time);
- * - `section`: a section of the conversation's properties panel;
- * - `inline`: an inline card in the conversation, hanging off a tool result (`ToolResult.card`);
- * - `page`: an org page under "Extensions";
- * - `file-preview`: an embed previewer of `file-preview@1` (embed only, see `FilePreviewer.embed`);
- * - `conversation`: the old right-side tab; it means `panel` (see {@link normalizePlace}).
+ * The places of the first UI design, kept as a deprecated input (UI slots spec §4, step A): each maps
+ * to a slot through `PLACE_SLOTS` (`panel` and `conversation` → `conversation.panel`, `section` →
+ * `conversation.properties.section`, `inline` → `conversation.tool-result.card`, `page` →
+ * `org.page`, `file-preview` → `file.preview`).
  */
 export type UiPlace = "conversation" | "panel" | "section" | "inline" | "page" | "file-preview";
-/** A place with the old `conversation` mapped to `panel`. */
-export declare function normalizePlace(place: UiPlace): Exclude<UiPlace, "conversation">;
 /**
  * Icons a contribution may use (design system icon names; `puzzle` is the default and is drawn as
  * the design `extension` icon). The title-bar button of a panel shows it.
@@ -20,8 +15,9 @@ export declare function normalizePlace(place: UiPlace): Exclude<UiPlace, "conver
 export declare const UI_ICONS: readonly ["list-checks", "layout-grid", "file", "chart", "calendar", "users", "bot", "book", "message-square", "puzzle"];
 export type UiIcon = (typeof UI_ICONS)[number];
 /**
- * An "open" target: a `panel` contribution of the same extension, scrolled to the block or item
- * whose `id` equals `item` (the panel's render receives it as {@link UiRenderArgs.item}).
+ * An "open" target: a `conversation.panel` contribution of the same extension, scrolled to the
+ * block or item whose `id` equals `item` (the panel's render receives it as
+ * {@link UiRenderArgs.item}).
  */
 export interface UiOpen {
     contribution: string;
@@ -39,7 +35,19 @@ export interface UiContribution {
         zh: string;
         en: string;
     };
-    place: UiPlace;
+    /**
+     * The slot it goes in: `"<id>"` (version 1) or `"<id>@<n>"`, an id of `UI_SLOTS`. Exactly one of
+     * `slot` and `place`. An unknown slot or version does not fail the extension: the contribution is
+     * dropped (see `resolveUiSlots`).
+     */
+    slot?: string;
+    /** @deprecated use slot (UI slots spec §4, step A) */
+    place?: UiPlace;
+    /**
+     * One of the slot's `anchors` to be placed after; omitted (or not an anchor of the slot) = the
+     * slot's first anchor.
+     */
+    after?: string;
     kind: UiKind;
     /** 仅 embed：插件路由下 `/ui/` 开头的路径，须在 `permissions.http` 中声明为 GET。 */
     path?: string;
@@ -150,20 +158,41 @@ export declare const UI_LIMITS: {
  */
 export declare function validateUiView(v: unknown): string[];
 /**
- * 调用者在组织内的角色（由高到低 owner / admin / member / guest）。`place: "page"` 的贡献只给 member 以上
- * （内核对 guest 返回 404，插件收不到 guest 的组织页面请求）；对话位置的贡献给能访问该对话的任何角色。
+ * The caller's role in the org (owner / admin / member / guest, highest first). A slot's `minRole`
+ * decides who may use its contributions, then its scope's rule (the kernel answers 404 to anyone
+ * else, so the extension never sees such a request): `org.page` member and up,
+ * `org.settings.section` admin and up; conversation slots any role that can read the
+ * conversation; `agent.detail.section` any role that can read the agent (read-only viewers
+ * included: tighten on `role` if you must).
  */
 export type UiRole = "owner" | "admin" | "member" | "guest";
-/** 内核调用插件 `render` 时传入的参数（身份由内核鉴权后给出，插件拿不到用户的会话凭据）。 */
-export interface UiRenderArgs {
-    orgId: string;
+/** The render args every scope shares (identity comes from the kernel's auth, never the caller's credentials). */
+export interface UiRenderArgsBase {
     accountId: string;
+    /** The catalog slot the contribution resolved to. */
+    slot: UiSlotId;
+    locale: Locale;
+    signal: AbortSignal;
+    /**
+     * The extension's effective deployment config: for an org, the platform's deployment config
+     * with the org's copy applied to the overridable fields (`orgAccess(…, "override")`), or the
+     * platform's config (equal to `ctx.config`) while the org follows it; for the platform scope,
+     * the platform's config. Use it, not `ctx.config`, for work done for this org. Optional in the
+     * type so older extensions compile; the kernel always passes it.
+     */
+    config?: unknown;
+}
+/** 内核调用插件 `render` 时传入的参数，组织内的位置（会话、智能体、组织、文件）。 */
+export interface UiOrgRenderArgs extends UiRenderArgsBase {
+    /** The scope of {@link slot}: which of the context ids below are set. */
+    scope: Exclude<UiSlotScope, "platform">;
+    orgId: string;
     /** 调用者此刻在 `orgId` 的角色（内核按成员关系填，插件可据此收紧按钮等，见 {@link UiRole}）。 */
     role: UiRole;
     /** 仅对话视图。 */
     conversationId?: string;
-    locale: Locale;
-    signal: AbortSignal;
+    /** Only an agent view (`agent.detail.section`): an agent of `orgId` the caller can read. */
+    agentId?: string;
     /** A panel opened from an open target: the block or item `id` to scroll to. */
     item?: string;
     /**
@@ -175,21 +204,36 @@ export interface UiRenderArgs {
         callId: string;
         key?: string;
     };
-    /**
-     * The extension's effective deployment config for this org: the platform's deployment config
-     * with the org's copy applied to the overridable fields (`orgAccess(…, "override")`), or the
-     * platform's config (equal to `ctx.config`) while the org follows it. Use it, not `ctx.config`,
-     * for work done for this org. Optional in the type so older extensions compile; the kernel
-     * always passes it.
-     */
-    config?: unknown;
 }
-/** 视图里的按钮或表单提交：`actionId` 来自块；表单提交时带 `answer`。 */
-export interface UiActionArgs extends UiRenderArgs {
+/**
+ * The render args of a `platform.page` contribution: rendered for a super admin in the admin
+ * console, with no org (and so no org role, conversation or agent).
+ */
+export interface UiPlatformRenderArgs extends UiRenderArgsBase {
+    scope: "platform";
+    orgId?: undefined;
+    role: "superAdmin";
+    conversationId?: undefined;
+    agentId?: undefined;
+    item?: undefined;
+    card?: undefined;
+}
+/** 内核调用插件 `render` 时传入的参数：narrow on `scope` (`"platform"` has no `orgId`). */
+export type UiRenderArgs = UiOrgRenderArgs | UiPlatformRenderArgs;
+/** What a button or form submit adds to the render args. */
+export interface UiActionInput {
     actionId: string;
     payload?: unknown;
     answer?: FormAnswer;
 }
+/** An action of an org-scope view. */
+export interface UiOrgActionArgs extends UiOrgRenderArgs, UiActionInput {
+}
+/** An action of a `platform.page` view. */
+export interface UiPlatformActionArgs extends UiPlatformRenderArgs, UiActionInput {
+}
+/** 视图里的按钮或表单提交：`actionId` 来自块；表单提交时带 `answer`。 */
+export type UiActionArgs = UiOrgActionArgs | UiPlatformActionArgs;
 /** 动作结果：一条提示，或一份新的视图。 */
 export type UiActionResult = {
     toast?: {
@@ -199,21 +243,55 @@ export type UiActionResult = {
 } | {
     view: UiView;
 };
-/** 嵌入令牌里的声明（经 `ctx.ui.verifyEmbedToken` 校验后可信）。`exp` 为 Unix 秒。 */
-export interface EmbedClaims {
+/** The embed claims both scopes share. `exp` 为 Unix 秒。 */
+export interface EmbedClaimsBase {
     plugin: string;
-    orgId: string;
     accountId: string;
+    contribution: string;
+    exp: number;
+}
+/** An org-scope embed token's claims (every slot but `platform.page`). */
+export interface OrgEmbedClaims extends EmbedClaimsBase {
+    scope: "org";
+    orgId: string;
     /** 调用者的角色：签发时写入；`ctx.ui.verifyEmbedToken` 返回校验时刻的当前角色。 */
     role: UiRole;
     conversationId?: string;
+    /** Only an agent embed's token (`agent.detail.section`): the agent it was issued for. */
+    agentId?: string;
     /** Only a `file-preview` embed's token: the one file (of `conversationId`) it previews. */
     fileId?: string;
-    contribution: string;
-    exp: number;
 }
+/** A `platform.page` embed token's claims: a super admin's, with no org, conversation, agent or file. */
+export interface PlatformEmbedClaims extends EmbedClaimsBase {
+    scope: "platform";
+    orgId?: undefined;
+    role: "superAdmin";
+    conversationId?: undefined;
+    agentId?: undefined;
+    fileId?: undefined;
+}
+/**
+ * 嵌入令牌里的声明（经 `ctx.ui.verifyEmbedToken` 校验后可信）: narrow on `scope` (`"platform"` has no
+ * `orgId` and `role` `"superAdmin"`).
+ */
+export type EmbedClaims = OrgEmbedClaims | PlatformEmbedClaims;
 /** 外层页面与嵌入 iframe 之间 `postMessage` 协议的版本标识。 */
 export declare const EMBED_PROTOCOL = "capybara-embed/1";
+/**
+ * What an embed's `init` says about where it is shown, narrowed on `scope` like {@link EmbedClaims}:
+ * an org's page, panel, section or previewer (`orgId`, and the conversation when there is one), or
+ * a platform page of the admin console (no org).
+ */
+export type EmbedInitContext = {
+    scope: "org";
+    orgId: string;
+    conversationId?: string;
+} | {
+    scope: "platform";
+    orgId?: undefined;
+    conversationId?: undefined;
+};
 /** 外层页面发给 iframe 的消息。 */
 export type EmbedParentMessage = {
     protocol: typeof EMBED_PROTOCOL;
@@ -222,10 +300,7 @@ export type EmbedParentMessage = {
     locale: Locale;
     theme: "dark" | "light";
     tokens: Record<string, string>;
-    context: {
-        orgId: string;
-        conversationId?: string;
-    };
+    context: EmbedInitContext;
 } | {
     protocol: typeof EMBED_PROTOCOL;
     type: "token";

package/dist/ui.js

@@ -1,9 +1,5 @@
 import { validateInputForm } from "./tool.js";
 import { isHttpUrl } from "./url.js";
-/** A place with the old `conversation` mapped to `panel`. */
-export function normalizePlace(place) {
-    return place === "conversation" ? "panel" : place;
-}
 /**
  * Icons a contribution may use (design system icon names; `puzzle` is the default and is drawn as
  * the design `extension` icon). The title-bar button of a panel shows it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.9",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {
@@ -29,6 +29,7 @@
   ],
   "dependencies": {
     "kysely": "^0.29.6",
+    "saxes": "6.0.0",
     "semver": "^7.8.5",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"

package/schemas/plugin.v1.schema.json

@@ -194,6 +194,25 @@
         "additionalProperties": false
       }
     },
+    "themes": {
+      "maxItems": 10,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 512,
+            "pattern": "^\\.\\/"
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "additionalProperties": false
+      }
+    },
     "setupGuides": {
       "maxItems": 8,
       "type": "array",

package/schemas/theme.v1.schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://capybarahq.com/schemas/theme.v1.schema.json",
+  "title": "Capybara theme file themes/<id>.json",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "maxLength": 512
+    },
+    "name": {
+      "type": "object",
+      "properties": {
+        "zh": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "\\S"
+        },
+        "en": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "\\S"
+        }
+      },
+      "required": [
+        "zh",
+        "en"
+      ],
+      "additionalProperties": false
+    },
+    "description": {
+      "type": "object",
+      "properties": {
+        "en": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "pattern": "\\S"
+        },
+        "zh": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "pattern": "\\S"
+        }
+      },
+      "required": [
+        "en"
+      ],
+      "additionalProperties": false
+    },
+    "schemes": {
+      "type": "object",
+      "properties": {
+        "dark": {
+          "type": "object",
+          "properties": {
+            "color": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 256
+              }
+            },
+            "shadow": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 256
+              }
+            },
+            "radius": {
+              "type": "object",
+              "properties": {
+                "sm": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 16
+                },
+                "md": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 16
+                },
+                "bubble": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 16
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "light": {
+          "type": "object",
+          "properties": {
+            "color": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 256
+              }
+            },
+            "shadow": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 256
+              }
+            },
+            "radius": {
+              "type": "object",
+              "properties": {
+                "sm": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 16
+                },
+                "md": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 16
+                },
+                "bubble": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 16
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "fonts": {
+      "maxItems": 8,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "family": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9 -]{1,64}$"
+          },
+          "file": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "weight": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 900
+          },
+          "style": {
+            "type": "string",
+            "enum": [
+              "normal",
+              "italic"
+            ]
+          },
+          "role": {
+            "type": "string",
+            "enum": [
+              "prose",
+              "mono"
+            ]
+          }
+        },
+        "required": [
+          "family",
+          "file",
+          "weight",
+          "role"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "logo": {
+      "type": "object",
+      "properties": {
+        "mark": {
+          "type": "string",
+          "maxLength": 512
+        },
+        "wordmark": {
+          "type": "string",
+          "pattern": "\\S"
+        },
+        "favicon": {
+          "type": "string",
+          "maxLength": 512
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "name",
+    "schemes"
+  ],
+  "additionalProperties": false
+}