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

package/agent-docs/extension-points/sandbox.md

@@ -2,7 +2,7 @@
 
 <!-- generated:extension-point -->
 - Name: `sandbox` (a ref is `sandbox@<major>`)
-- Runs an environment's instance and keeps its files for agents' commands (Docker, E2B).
+- Runs a device's instance and keeps its files for agents' commands (Docker, E2B).
 - Providers: one at a time
 - Enabled per org: no
 - Brokered by the platform: yes (extensions use it only through `ctx`)
@@ -10,6 +10,6 @@
 
 Contract: SandboxProvider (`sandbox.ts`)
 
-The kernel accepts only `sandbox@2`. An environment is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours. Never publish a docker socket proxy on a host address.
+The kernel accepts only `sandbox@2`. A device is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours. Never publish a docker socket proxy on a host address.
 
 See `extensions` for the rules every extension follows.

package/agent-docs/extensions.md

@@ -44,7 +44,7 @@ look like `channel@1`: name and major version. The registered points:
 <!-- generated:extension-points -->
 | Extension point | Providers | Per org | What it is |
 |---|---|---|---|
-| `sandbox` | single | no | Runs an environment's instance and keeps its files for agents' commands (Docker, E2B). |
+| `sandbox` | single | no | Runs a device's instance and keeps its files for agents' commands (Docker, E2B). |
 | `config-source` | single | no | Supplies deployment configuration from an external store such as Nacos. |
 | `secret-store` | single | no | Stores and resolves secrets (connector credentials, secret config) outside the database. |
 | `object-store` | single | no | Stores files and artifacts in S3-compatible object storage, with presigned uploads. |

package/dist/ctx.d.ts

@@ -198,15 +198,20 @@ export interface ExtensionContext {
      * 界面贡献的运行时（清单 `ui` + `permissions.ui`）：
      * - `view` / `action`：只能在 `setup` 期间注册，id 是清单里 kind view 的贡献 id；
      *   `action` 收到视图里按钮或表单提交（`args.actionId` 区分是哪一个）；
-     * - `invalidate`：告诉内核「这个贡献变了」，打开着它的网页会重新取视图（经 bus，跨副本）；
+     * - `invalidate`：告诉内核「这个贡献变了」，打开着它的网页会重新取视图（经 bus，跨副本）；a
+     *   `platform.page` contribution takes no `orgId` (it refreshes the admin console), every other
+     *   contribution requires one;
      * - `verifyEmbedToken`：校验 embed 页面拿到的嵌入令牌，只认签给本插件、未过期的，且此刻插件仍在该组织启用、
-     *   调用者仍是 active 成员（组织页面还要求 member 以上），否则返回 null；返回的 `role` 是此刻的角色。
+     *   调用者仍是 active 成员，角色仍满足位置的 minRole，否则返回 null；返回的 `role` 是此刻的角色。A
+     *   platform-scope token (`scope: "platform"`, no `orgId`) verifies only for a `platform.page`
+     *   contribution while the account is still an active super admin.
      */
     ui: {
         view(id: string, render: (args: UiRenderArgs) => Promise<UiView>): void;
         action(id: string, handler: (args: UiActionArgs) => Promise<UiActionResult>): void;
         invalidate(target: {
-            orgId: string;
+            /** Required, except for a `platform.page` contribution, where it must be omitted. */
+            orgId?: string;
             conversationId?: string;
             contribution: string;
         }): Promise<void>;

package/dist/define-extension.d.ts

@@ -14,7 +14,11 @@ export interface ExtensionManifest {
     optional?: ExtensionPointRef[];
     /** 权限清单（治理而非沙箱）。 */
     permissions?: ExtensionPermissions;
-    /** 界面贡献：对话页标签与组织页面；id 须同时列在 `permissions.ui` 里。 */
+    /**
+     * UI contributions, each in a slot of `UI_SLOTS`; every id is also listed in `permissions.ui`.
+     * Kept exactly as written: structural problems fail the extension, while a contribution to an
+     * unknown slot or version is only dropped when the host resolves the slots (`resolveUiSlots`).
+     */
     ui?: UiContribution[];
     config?: {
         deployment?: z.ZodTypeAny;

package/dist/define-extension.js

@@ -78,6 +78,7 @@ export function defineExtension(m) {
         if (errs.length > 0)
             fail(`invalid permissions: ${errs.join("; ")}`);
     }
+    // structural ui problems only; slot resolution never fails the extension (UI slots spec §3.2)
     const uiErrs = validateUiContributions(m.ui, m.permissions);
     if (uiErrs.length > 0)
         fail(`invalid ui: ${uiErrs.join("; ")}`);

package/dist/device-protocol.d.ts

@@ -1,6 +1,6 @@
 /**
  * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
- * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ * (a connected machine that serves as a device). Pure types and hand-written guards.
  */
 import { type ExecResult, type SandboxActor, type SandboxLimits, type SandboxRoots } from "./sandbox.js";
 /** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */

package/dist/device-protocol.js

@@ -1,6 +1,6 @@
 /**
  * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
- * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ * (a connected machine that serves as a device). Pure types and hand-written guards.
  */
 import { validateSandboxPathShape, } from "./sandbox.js";
 /** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */

package/dist/extension-point.js

@@ -8,7 +8,7 @@ const info = (majors, description, cardinality, brokered = false, orgScoped = fa
 });
 /** The registered extension points. */
 export const EXTENSION_POINTS = {
-    sandbox: info([2], "Runs an environment's instance and keeps its files for agents' commands (Docker, E2B).", "single", true),
+    sandbox: info([2], "Runs a device's instance and keeps its files for agents' commands (Docker, E2B).", "single", true),
     "config-source": info([1], "Supplies deployment configuration from an external store such as Nacos.", "single"),
     "secret-store": info([1], "Stores and resolves secrets (connector credentials, secret config) outside the database.", "single", true),
     "object-store": info([1], "Stores files and artifacts in S3-compatible object storage, with presigned uploads.", "single", true),

package/dist/file-preview.d.ts

@@ -7,7 +7,7 @@ export declare const FILE_PREVIEW_MAX_BYTES: number;
 /**
  * One previewer of a `file-preview@1` provider: which files it previews and how. It renders either a
  * view (`render`, drawn by the web app like any `UiView`) or an embed page (`embed`, the id of a ui
- * contribution `{ kind: "embed", place: "file-preview" }` of the same extension, which receives the
+ * contribution `{ kind: "embed", slot: "file.preview" }` of the same extension, which receives the
  * file over the message bridge). Exactly one of the two.
  */
 export interface FilePreviewer {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.8";
+export declare const SDK_VERSION = "0.1.0-rc.9";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -34,4 +34,6 @@ export * from "./theme-tokens.generated.js";
 export * from "./tool.js";
 export * from "./tool-key.js";
 export * from "./ui.js";
+export * from "./ui-resolve.js";
+export * from "./ui-slots.js";
 export * from "./web.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.8";
+export const SDK_VERSION = "0.1.0-rc.9";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -34,4 +34,6 @@ export * from "./theme-tokens.generated.js";
 export * from "./tool.js";
 export * from "./tool-key.js";
 export * from "./ui.js";
+export * from "./ui-resolve.js";
+export * from "./ui-slots.js";
 export * from "./web.js";

package/dist/permissions.d.ts

@@ -62,9 +62,14 @@ export declare class ExtensionPointUnavailableError extends Error {
 /** 校验权限清单，返回错误列表（空表示合法）。 */
 export declare function validatePermissions(plugin: string, p: unknown): string[];
 /**
- * 校验清单 `ui` 并与权限清单交叉核对，返回错误列表（空表示合法）：
- * 每个贡献的 id 恰好出现在 `permissions.ui.views`（kind view）或 `permissions.ui.embeds`（kind embed）里，
- * `permissions.ui` 里也不能有清单 `ui` 没有的 id；embed 的 path 以 `/ui/` 开头并在 `permissions.http` 中声明为 GET。
- * 假定 `permissions` 已经过 {@link validatePermissions}。
+ * Checks the structure of the manifest's `ui` and cross-checks it with the permission manifest;
+ * returns the problems (empty = valid). Only structural problems (UI slots spec §3.2): each
+ * contribution's id is listed in exactly `permissions.ui.views` (kind view) or
+ * `permissions.ui.embeds` (kind embed), and `permissions.ui` lists no id the `ui` lacks; an embed's
+ * path starts with `/ui/` and is declared in `permissions.http` as GET; exactly one of `slot` (a
+ * well-formed slot reference) and `place` (a known place); for a slot the catalog knows at the
+ * version named, a kind it accepts and, unless an alias, the icon it requires. An unknown slot id or version is not a
+ * problem here: `resolveUiSlots` drops that contribution and the rest of the extension loads.
+ * Assumes `permissions` passed {@link validatePermissions}.
  */
 export declare function validateUiContributions(ui: unknown, permissions: unknown): string[];

package/dist/permissions.js

@@ -1,5 +1,6 @@
 import { POLICY_HOOKS } from "./hooks.js";
 import { UI_ICONS } from "./ui.js";
+import { PLACE_SLOTS, parseSlotRef, uiSlot } from "./ui-slots.js";
 /** hook 挂载点（封闭列表，见总设计 2.4）。 */
 export const HOOK_MOUNT_POINTS = [
     "session.start",
@@ -168,20 +169,18 @@ export function validatePermissions(plugin, p) {
 }
 const UI_ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
 const UI_TITLE_MAX = 100;
-const UI_PLACES = [
-    "conversation",
-    "panel",
-    "section",
-    "inline",
-    "page",
-    "file-preview",
-];
+const UI_PLACES = Object.keys(PLACE_SLOTS);
 const UI_EMBED_PREFIX = "/ui/";
 /**
- * 校验清单 `ui` 并与权限清单交叉核对，返回错误列表（空表示合法）：
- * 每个贡献的 id 恰好出现在 `permissions.ui.views`（kind view）或 `permissions.ui.embeds`（kind embed）里，
- * `permissions.ui` 里也不能有清单 `ui` 没有的 id；embed 的 path 以 `/ui/` 开头并在 `permissions.http` 中声明为 GET。
- * 假定 `permissions` 已经过 {@link validatePermissions}。
+ * Checks the structure of the manifest's `ui` and cross-checks it with the permission manifest;
+ * returns the problems (empty = valid). Only structural problems (UI slots spec §3.2): each
+ * contribution's id is listed in exactly `permissions.ui.views` (kind view) or
+ * `permissions.ui.embeds` (kind embed), and `permissions.ui` lists no id the `ui` lacks; an embed's
+ * path starts with `/ui/` and is declared in `permissions.http` as GET; exactly one of `slot` (a
+ * well-formed slot reference) and `place` (a known place); for a slot the catalog knows at the
+ * version named, a kind it accepts and, unless an alias, the icon it requires. An unknown slot id or version is not a
+ * problem here: `resolveUiSlots` drops that contribution and the rest of the extension loads.
+ * Assumes `permissions` passed {@link validatePermissions}.
  */
 export function validateUiContributions(ui, permissions) {
     const perms = isObj(permissions) ? permissions : {};
@@ -219,22 +218,46 @@ export function validateUiContributions(ui, permissions) {
         if (!title ||
             [title.zh, title.en].some((t) => typeof t !== "string" || t === "" || t.length > UI_TITLE_MAX))
             errs.push(`ui "${id}" title needs non-empty zh and en of at most ${UI_TITLE_MAX} characters`);
-        if (!UI_PLACES.includes(c.place))
+        // the slot it names, when the slot / place is well formed (known to the catalog or not)
+        let slotRef = null;
+        if ((c.slot === undefined) === (c.place === undefined)) {
+            errs.push(`ui "${id}" needs exactly one of slot and place`);
+        }
+        else if (c.slot !== undefined) {
+            slotRef = typeof c.slot === "string" ? parseSlotRef(c.slot) : null;
+            if (slotRef === null)
+                errs.push(`ui "${id}" slot must be a slot reference like "org.page" or "org.page@1"`);
+        }
+        else if (!UI_PLACES.includes(c.place)) {
             errs.push(`ui "${id}" place must be one of ${UI_PLACES.join(", ")}`);
+        }
+        else {
+            slotRef = { id: PLACE_SLOTS[c.place], version: 1 };
+        }
+        if (c.after !== undefined && typeof c.after !== "string")
+            errs.push(`ui "${id}" after must be a string`);
         if (c.kind !== "view" && c.kind !== "embed") {
             errs.push(`ui "${id}" kind must be view or embed`);
             return;
         }
         if (c.icon !== undefined && !UI_ICONS.includes(c.icon))
             errs.push(`ui "${id}" icon must be one of ${UI_ICONS.join(", ")}`);
+        // the slot checks describe only the catalog's version: another version is left to
+        // resolveUiSlots, which drops it (unsupported-version) without failing the extension
+        const known = slotRef === null ? undefined : uiSlot(slotRef.id);
+        const spec = known !== undefined && known.version === slotRef?.version ? known : undefined;
+        if (spec !== undefined) {
+            if (!spec.accepts.includes(c.kind))
+                errs.push(`ui "${id}" slot ${spec.id} does not accept kind ${c.kind}`);
+            if (spec.icon === "required" && c.icon === undefined && c.aliasOf === undefined)
+                errs.push(`ui "${id}" slot ${spec.id} needs an icon`);
+        }
         if (c.aliasOf !== undefined)
             aliases.push({ id, kind: c.kind, target: c.aliasOf });
         if (seen.has(id))
             errs.push(`ui has duplicate id "${id}"`);
         seen.set(id, c.kind);
         if (c.kind === "view") {
-            if (c.place === "file-preview")
-                errs.push(`ui "${id}" place file-preview is only allowed for kind embed`);
             if (c.path !== undefined)
                 errs.push(`ui "${id}" path is only allowed for kind embed`);
             if (!views.includes(id))

package/dist/sandbox.d.ts

@@ -4,8 +4,8 @@
  * primitives below; the kernel builds `glob` / `grep` / `edit` from `exec` plus `readFile` /
  * `writeFile`.
  *
- * `@2` separates an environment's **file system** from its **instance**: the file system
- * (`createFileSystem`) lives until the environment is deleted (`destroyFileSystem`); instances
+ * `@2` separates a device's **file system** from its **instance**: the file system
+ * (`createFileSystem`) lives until the device is deleted (`destroyFileSystem`); instances
  * (`create`) attach to it and come and go (`destroy` drops the instance and keeps the files).
  */
 /** Sandbox extension point ref. */
@@ -38,7 +38,7 @@ export interface SandboxHandle {
 }
 /** The roots of an instance, falling back to {@link DEFAULT_SANDBOX_ROOTS}. */
 export declare function rootsOf(h: SandboxHandle): SandboxRoots;
-/** The provider's file system handle (an environment's files, independent of any instance). */
+/** The provider's file system handle (a device's files, independent of any instance). */
 export interface FileSystemHandle {
     /** The provider's file system id. */
     id: string;
@@ -74,7 +74,7 @@ export declare function isSandboxGoneError(e: unknown): e is SandboxGoneError;
 /**
  * The file system is definitely gone on the provider's side (volume removed, E2B sandbox killed).
  * `create` throws it instead of attaching the instance to a new, empty file system; the kernel then
- * reports the environment's files as lost rather than handing out a silently empty workspace.
+ * reports the device's files as lost rather than handing out a silently empty workspace.
  */
 export declare class FileSystemGoneError extends Error {
     readonly fileSystemGone: true;
@@ -93,8 +93,8 @@ export declare const SANDBOX_TAG_RE: RegExp;
 /**
  * The `sandbox@2` implementation (provided by a sandbox plugin such as Docker or E2B).
  *
- * **File systems and instances.** `createFileSystem` makes an environment's files; they live until
- * `destroyFileSystem` (the environment is deleted). `create` makes an instance attached to an
+ * **File systems and instances.** `createFileSystem` makes a device's files; they live until
+ * `destroyFileSystem` (the device is deleted). `create` makes an instance attached to an
  * existing file system; `destroy` / `destroyByName` drop the instance only and keep the files, and
  * `suspend` keeps them too. When the file system is gone, `create` must throw
  * {@link FileSystemGoneError} and never create an empty one in its place (a Docker provider checks
@@ -126,7 +126,7 @@ export declare const SANDBOX_TAG_RE: RegExp;
  * `exitCode: null`, `timedOut: false` (and the output collected so far), it does not reject. An
  * `exec` called with an already aborted signal rejects at once.
  *
- * **Concurrent use** (required in `@2`): the sessions of one environment share its instance, so the
+ * **Concurrent use** (required in `@2`): the sessions of one device share its instance, so the
  * kernel calls `exec`, `readFile`, `writeFile` and `stat` concurrently on one instance. Those four
  * methods must be safe to call concurrently. Each `exec` labels its command with its `tag`, and an
  * aborted `exec` kills only its own command.
@@ -135,12 +135,12 @@ export interface SandboxProvider {
     /** `exec` / `readFile` / `writeFile` / `stat` may run concurrently on one instance (required). */
     readonly concurrentExec: true;
     /**
-     * Whether the provider isolates the sessions of one environment from each other inside the
+     * Whether the provider isolates the sessions of one device from each other inside the
      * instance (a declared capability; absent means false).
      */
     readonly sessionIsolation?: boolean;
     /**
-     * Creates an environment's file system. `name` looks like `cap-env-<environmentId>`. If a file
+     * Creates a device's file system. `name` looks like `cap-device-<deviceId>`. If a file
      * system with this name already exists, return it.
      */
     createFileSystem(args: {

package/dist/sandbox.js

@@ -4,8 +4,8 @@
  * primitives below; the kernel builds `glob` / `grep` / `edit` from `exec` plus `readFile` /
  * `writeFile`.
  *
- * `@2` separates an environment's **file system** from its **instance**: the file system
- * (`createFileSystem`) lives until the environment is deleted (`destroyFileSystem`); instances
+ * `@2` separates a device's **file system** from its **instance**: the file system
+ * (`createFileSystem`) lives until the device is deleted (`destroyFileSystem`); instances
  * (`create`) attach to it and come and go (`destroy` drops the instance and keeps the files).
  */
 /** Sandbox extension point ref. */
@@ -45,7 +45,7 @@ export function isSandboxGoneError(e) {
 /**
  * The file system is definitely gone on the provider's side (volume removed, E2B sandbox killed).
  * `create` throws it instead of attaching the instance to a new, empty file system; the kernel then
- * reports the environment's files as lost rather than handing out a silently empty workspace.
+ * reports the device's files as lost rather than handing out a silently empty workspace.
  */
 export class FileSystemGoneError extends Error {
     fileSystemGone = true;

package/dist/tool.d.ts

@@ -72,9 +72,9 @@ export interface ToolResult {
     display?: ToolDisplay;
     /**
      * Optional: an inline card under this call in the conversation: `view` is a ui contribution of
-     * the same extension with `place: "inline"`, rendered with `card: { callId, key }`. Display only
-     * (recorded on the `tool_result` event, never in the model's context); an unknown view is dropped
-     * with a warning and the result is kept.
+     * the same extension in the `conversation.tool-result.card` slot, rendered with
+     * `card: { callId, key }`. Display only (recorded on the `tool_result` event, never in the model's
+     * context); an unknown view is dropped with a warning and the result is kept.
      */
     card?: {
         view: string;

package/dist/ui-resolve.d.ts

@@ -0,0 +1,40 @@
+import type { UiContribution } from "./ui.js";
+import { type UiSlotSpec } from "./ui-slots.js";
+/** A contribution whose slot the catalog knows at the version it names (UI slots spec §3.2). */
+export interface ResolvedUiContribution {
+    contribution: UiContribution;
+    slot: UiSlotSpec;
+    version: number;
+    /**
+     * For a slot with anchors: the anchor it goes after (the contribution's own `after` when it is one
+     * of the slot's anchors, else the slot's first anchor). Absent for a slot without anchors.
+     */
+    after?: string;
+}
+/** Why a contribution was dropped: its slot is not in the catalog, or not at that version. */
+export type UiDropReason = "unknown-slot" | "unsupported-version";
+/** A contribution left out of the loaded extension; `ref` is the slot reference it names. */
+export interface DroppedUiContribution {
+    id: string;
+    ref: string;
+    reason: UiDropReason;
+}
+/** The slot reference a contribution names: its `slot`, or the slot of its deprecated `place`. */
+export declare function slotRefOf(c: UiContribution): string;
+/**
+ * Resolves the slots of a manifest's `ui` against the catalog (UI slots spec §3.2). Assumes
+ * `validateUiContributions` passed; never throws. A contribution to an unknown slot or to a version
+ * other than the slot's is dropped (an alias whose target is dropped is dropped with the target's
+ * reason and its own `ref`); an `after` that is not an anchor of the slot is listed in
+ * `unknownAnchors` and the contribution keeps the slot's default position. `deprecatedPlace` lists
+ * the ids that still say `place`. Both lists keep manifest order.
+ */
+export declare function resolveUiSlots(ui: readonly UiContribution[] | undefined): {
+    resolved: ResolvedUiContribution[];
+    dropped: DroppedUiContribution[];
+    unknownAnchors: {
+        id: string;
+        after: string;
+    }[];
+    deprecatedPlace: string[];
+};

package/dist/ui-resolve.js

@@ -0,0 +1,54 @@
+import { PLACE_SLOTS, parseSlotRef, uiSlot } from "./ui-slots.js";
+/** The slot reference a contribution names: its `slot`, or the slot of its deprecated `place`. */
+export function slotRefOf(c) {
+    // biome-ignore lint/style/noNonNullAssertion: validateUiContributions requires slot or place
+    return c.slot ?? PLACE_SLOTS[c.place];
+}
+/**
+ * Resolves the slots of a manifest's `ui` against the catalog (UI slots spec §3.2). Assumes
+ * `validateUiContributions` passed; never throws. A contribution to an unknown slot or to a version
+ * other than the slot's is dropped (an alias whose target is dropped is dropped with the target's
+ * reason and its own `ref`); an `after` that is not an anchor of the slot is listed in
+ * `unknownAnchors` and the contribution keeps the slot's default position. `deprecatedPlace` lists
+ * the ids that still say `place`. Both lists keep manifest order.
+ */
+export function resolveUiSlots(ui) {
+    const list = ui ?? [];
+    const own = new Map();
+    for (const c of list) {
+        const ref = parseSlotRef(slotRefOf(c));
+        const slot = ref === null ? undefined : uiSlot(ref.id);
+        own.set(c.id, ref === null || slot === undefined
+            ? { ok: false, reason: "unknown-slot" }
+            : ref.version !== slot.version
+                ? { ok: false, reason: "unsupported-version" }
+                : { ok: true, slot, version: ref.version });
+    }
+    const resolved = [];
+    const dropped = [];
+    const unknownAnchors = [];
+    const deprecatedPlace = [];
+    for (const c of list) {
+        if (c.slot === undefined && c.place !== undefined)
+            deprecatedPlace.push(c.id);
+        const mine = own.get(c.id);
+        const target = c.aliasOf === undefined ? undefined : own.get(c.aliasOf);
+        const r = mine.ok && target !== undefined && !target.ok ? target : mine;
+        if (!r.ok) {
+            dropped.push({ id: c.id, ref: slotRefOf(c), reason: r.reason });
+            continue;
+        }
+        const anchors = r.slot.anchors ?? [];
+        if (c.after !== undefined && !anchors.includes(c.after)) {
+            unknownAnchors.push({ id: c.id, after: c.after });
+        }
+        const after = c.after !== undefined && anchors.includes(c.after) ? c.after : anchors[0];
+        resolved.push({
+            contribution: c,
+            slot: r.slot,
+            version: r.version,
+            ...(anchors.length > 0 && { after }),
+        });
+    }
+    return { resolved, dropped, unknownAnchors, deprecatedPlace };
+}

package/dist/ui-slots.d.ts

@@ -0,0 +1,43 @@
+import type { UiKind, UiPlace } from "./ui.js";
+export type UiSlotScope = "conversation" | "agent" | "org" | "platform" | "file";
+export type UiSlotRole = "guest" | "member" | "admin" | "superAdmin";
+/** Every slot id of the catalog, in catalog order (UI slots spec §3). */
+export declare const UI_SLOT_IDS: readonly ["conversation.panel", "conversation.properties.section", "conversation.tool-result.card", "org.page", "file.preview", "agent.detail.section", "org.settings.section", "platform.page"];
+export type UiSlotId = (typeof UI_SLOT_IDS)[number];
+/** One slot of the catalog: where extension UI may go and what it receives (UI slots spec §3.1). */
+export interface UiSlotSpec {
+    id: UiSlotId;
+    /** Bumped only on an incompatible change of the slot's contract. */
+    version: number;
+    /** Path relative to `apps/web/src` of the component that renders the slot. */
+    owner: string;
+    scope: UiSlotScope;
+    accepts: readonly UiKind[];
+    cardinality: "list";
+    minRole: UiSlotRole;
+    /** Context ids passed to render (`conversationId`, `agentId`, …). */
+    args: readonly string[];
+    density: "dense" | "regular";
+    icon: "required" | "optional" | "none";
+    /** Built-in parts a contribution may be placed after; the first is the default. */
+    anchors?: readonly string[];
+    limits?: {
+        maxShown?: number;
+    };
+    description: {
+        en: string;
+        zh: string;
+    };
+}
+export declare const UI_SLOTS: readonly UiSlotSpec[];
+export declare function uiSlot(id: string): UiSlotSpec | undefined;
+/** Reads `<id>` or `<id>@<version>` (version 1 when omitted); does not check the catalog. */
+export declare function parseSlotRef(ref: string): {
+    id: string;
+    version: number;
+} | null;
+/** @deprecated step A of the UI slots spec §4 */
+export declare const PLACE_SLOTS: Readonly<Record<UiPlace, UiSlotId>>;
+export declare const UI_ARRANGEABLE_SLOTS: readonly UiSlotId[];
+export declare const UI_CONTRIBUTION_KEY_RE: RegExp;
+export declare function uiContributionKey(plugin: string, id: string): string;

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.8",
+  "version": "0.1.0-rc.9",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {