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

package/dist/tools/resources.d.ts

@@ -1,6 +1,6 @@
 import { type ConnectorSession, type ToolResult, type ToolSpec } from "@capybara-hq/plugin-sdk";
 /**
- * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ * 连接器 resources 的两个内核工具（brief：`mcp__<slug>__list_resources`、`mcp__<slug>__read_resource {uri}`）。
  *
  * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
  * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和

package/dist/tools/resources.js

@@ -1,6 +1,6 @@
 import { ToolError, } from "@capybara-hq/plugin-sdk";
 /**
- * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ * 连接器 resources 的两个内核工具（brief：`mcp__<slug>__list_resources`、`mcp__<slug>__read_resource {uri}`）。
  *
  * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
  * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和

package/dist/tools/tools.module.js

@@ -5,26 +5,36 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { BackgroundModule } from "../background/background.module.js";
 import { ConversationAccessModule } from "../conversations/access.js";
 import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
+import { DevicesModule } from "../devices/devices.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
+import { ModelsModule } from "../models/models.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
+import { PlatformModule } from "../platform/platform.module.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { StepLogModule } from "../runtime/step-log.js";
 import { SubagentsModule } from "../runtime/subagents/subagents.service.js";
+import { UsageReportModule } from "../runtime/usage-report.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { StorageModule } from "../storage/storage.module.js";
+import { AdminConnectors } from "./admin-connectors.js";
 import { ApprovalsService } from "./approvals.service.js";
 import { Breaker } from "./breaker.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
+import { WebPages } from "./builtins/web/page-cache.js";
+import { ConnectorAccountPolicies } from "./connector-account-policies.js";
 import { ConnectorContent } from "./connector-content.js";
 import { ConnectorsService } from "./connectors.service.js";
 import { Credentials } from "./credentials.js";
 import { ToolDrift } from "./drift.js";
-import { ConversationToolInfo } from "./info.js";
+import { ConversationToolInfo, OrgExtensionTools } from "./info.js";
 import { OAuthFlow } from "./oauth/flow.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
 import { ToolOutputs } from "./outputs.js";
 import { ToolPipeline } from "./pipeline.js";
 import { QuestionsService } from "./questions.service.js";
@@ -48,18 +58,28 @@ ToolsModule = __decorate([
             StorageModule,
             SkillsModule,
             OrgLockModule,
-            // the `agent` tool's dispatch
+            // the `Agent` tool's dispatch
             SubagentsModule,
-            // the builtin sandbox and skill tools run in the conversation's sandbox
+            // the builtin sandbox and skill tools run in the conversation's device
             SandboxModule,
+            DevicesModule,
+            // `Bash` with run_in_background records its task; TaskOutput / TaskStop finish and stop it
+            BackgroundModule,
             // the conversation page's tool metadata reads only what the viewer may see
             ConversationAccessModule,
+            // the WebFetch extraction call: its purpose, usage report and step writes
+            ModelsModule,
+            UsageReportModule,
+            StepLogModule,
+            // the `Platform` tool's operations, actor facts and agent docs (imports no domain module)
+            PlatformModule,
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
         providers: [
             Credentials,
             ToolOutputs,
             BuiltinTools,
+            WebPages,
             ToolRegistry,
             ApprovalsService,
             QuestionsService,
@@ -68,8 +88,12 @@ ToolsModule = __decorate([
             ConnectorContent,
             ToolPipeline,
             ConnectorsService,
+            AdminConnectors,
+            ConnectorAccountPolicies,
             OAuthFlow,
             ConversationToolInfo,
+            OrgExtensionTools,
+            OrgToolSwitches,
         ],
         exports: [
             Credentials,
@@ -83,8 +107,12 @@ ToolsModule = __decorate([
             ConnectorContent,
             ToolPipeline,
             ConnectorsService,
+            AdminConnectors,
+            ConnectorAccountPolicies,
             OAuthFlow,
             ConversationToolInfo,
+            OrgExtensionTools,
+            OrgToolSwitches,
         ],
     })
 ], ToolsModule);

package/dist/tools/validate.js

@@ -1,5 +1,5 @@
 import { Ajv2020 } from "ajv/dist/2020.js";
-import { canonicalJson } from "./registry.js";
+import { canonicalJson } from "./canonical-json.js";
 /**
  * 编译结果缓存的上限：超过后整体丢弃（工具定义每步从库里重新读出，缓存不能无限增长）。
  * 缓存的是由定义推导出的只读数据，不是跨进程状态。

package/dist/ui/admin-ui.controller.d.ts

@@ -0,0 +1,56 @@
+import type { UiActionResult, UiView } from "@capybara-hq/plugin-sdk";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { z } from "zod";
+import { ApiTokenService } from "../identity/api-tokens.js";
+import { type Principal } from "../identity/principal.js";
+import { SessionService } from "../identity/sessions.js";
+import { EmbedTokens } from "./embed-token.js";
+import { ContributionParams, PlatformActionBody, PlatformViewQuery } from "./ui.schemas.js";
+import { OrgUiStreams } from "./ui-stream.js";
+import { type UiArrangementSlot, type UiContributionItem, UiViews } from "./views.js";
+/**
+ * Extension UI in the admin console (UI slots spec §7, platform scope): the `platform.page`
+ * contributions, for super admins only (`@SuperAdmin`, a person: service tokens are refused), with
+ * no org. A platform contribution needs its extension running (no org enablement applies) and is
+ * given the platform's deployment config; its render args carry `scope: "platform"`, `role:
+ * "superAdmin"` and no `orgId`.
+ * - `GET  /api/v1/admin/ui/contributions` → `{ items }` (`platform.page` only, base order);
+ * - `GET  /api/v1/admin/ui/arrangement` → `{ slots }` over every arrangeable slot, the platform's
+ *   entries only, with every running extension's contributions (hidden ones marked);
+ * - `GET  /api/v1/admin/ui/views/:plugin/:id?locale=` → `{ view }`;
+ * - `POST /api/v1/admin/ui/actions/:plugin/:id` (`{ actionId, payload?, answer?, locale? }`) →
+ *   `{ toast }` | `{ view }`;
+ * - `POST /api/v1/admin/ui/embeds/:plugin/:id/token` → `{ token, src, expiresAt, expiresIn }`: a
+ *   platform embed token (`scope: "platform"`, `role: "superAdmin"`, no `orgId`), which
+ *   `ctx.ui.verifyEmbedToken` accepts only for a `platform.page` contribution while the account is
+ *   still an active super admin;
+ * - `GET  /api/v1/admin/ui/stream`: the platform refresh SSE (`event: ui`, topic `platform-ui`),
+ *   super admin re-checked on the `runtime.sseRecheckMs` interval.
+ * A contribution in any other slot is 404 `ui.not_found`, the same as one that does not exist.
+ */
+export declare class AdminUiController {
+    private readonly views;
+    private readonly streams;
+    private readonly sessions;
+    private readonly tokens;
+    private readonly embeds;
+    constructor(views: UiViews, streams: OrgUiStreams, sessions: SessionService, tokens: ApiTokenService, embeds: EmbedTokens);
+    contributions(principal: Principal): Promise<{
+        items: UiContributionItem[];
+    }>;
+    arrangement(principal: Principal): Promise<{
+        slots: UiArrangementSlot[];
+    }>;
+    view(principal: Principal, { plugin, id }: z.infer<typeof ContributionParams>, q: z.infer<typeof PlatformViewQuery>): Promise<{
+        view: UiView;
+    }>;
+    action(principal: Principal, { plugin, id }: z.infer<typeof ContributionParams>, body: z.infer<typeof PlatformActionBody>): Promise<UiActionResult>;
+    embedToken(principal: Principal, { plugin, id }: z.infer<typeof ContributionParams>): Promise<{
+        token: string;
+        src: string;
+        expiresAt: string;
+        expiresIn: number;
+    }>;
+    /** The platform refresh stream: written on the raw response (`reply.hijack()`) like the org one. */
+    stream(principal: Principal, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+}

package/dist/ui/admin-ui.controller.js

@@ -0,0 +1,192 @@
+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;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
+import { ApiTokenService } from "../identity/api-tokens.js";
+import { credentialCheck } from "../identity/credential-check.js";
+import { CurrentPrincipal, requireUser, SuperAdmin, } from "../identity/principal.js";
+import { SessionService } from "../identity/sessions.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
+import { EMBED_TOKEN_TTL_SECONDS, EmbedTokens } from "./embed-token.js";
+import { ContributionParams, PlatformActionBody, PlatformViewQuery } from "./ui.schemas.js";
+import { OrgUiStreams } from "./ui-stream.js";
+import { BEARER_RE, embedSrc } from "./views.controller.js";
+import { UiViews } from "./views.js";
+class AdminUiContributionParamsDto extends createZodDto(ContributionParams, "AdminUiContributionParams") {
+}
+class AdminUiViewQueryDto extends createZodDto(PlatformViewQuery, "AdminUiViewQuery") {
+}
+class AdminUiActionBodyDto extends createZodDto(PlatformActionBody, "AdminUiActionBody") {
+}
+/**
+ * Extension UI in the admin console (UI slots spec §7, platform scope): the `platform.page`
+ * contributions, for super admins only (`@SuperAdmin`, a person: service tokens are refused), with
+ * no org. A platform contribution needs its extension running (no org enablement applies) and is
+ * given the platform's deployment config; its render args carry `scope: "platform"`, `role:
+ * "superAdmin"` and no `orgId`.
+ * - `GET  /api/v1/admin/ui/contributions` → `{ items }` (`platform.page` only, base order);
+ * - `GET  /api/v1/admin/ui/arrangement` → `{ slots }` over every arrangeable slot, the platform's
+ *   entries only, with every running extension's contributions (hidden ones marked);
+ * - `GET  /api/v1/admin/ui/views/:plugin/:id?locale=` → `{ view }`;
+ * - `POST /api/v1/admin/ui/actions/:plugin/:id` (`{ actionId, payload?, answer?, locale? }`) →
+ *   `{ toast }` | `{ view }`;
+ * - `POST /api/v1/admin/ui/embeds/:plugin/:id/token` → `{ token, src, expiresAt, expiresIn }`: a
+ *   platform embed token (`scope: "platform"`, `role: "superAdmin"`, no `orgId`), which
+ *   `ctx.ui.verifyEmbedToken` accepts only for a `platform.page` contribution while the account is
+ *   still an active super admin;
+ * - `GET  /api/v1/admin/ui/stream`: the platform refresh SSE (`event: ui`, topic `platform-ui`),
+ *   super admin re-checked on the `runtime.sseRecheckMs` interval.
+ * A contribution in any other slot is 404 `ui.not_found`, the same as one that does not exist.
+ */
+let AdminUiController = class AdminUiController {
+    views;
+    streams;
+    sessions;
+    tokens;
+    embeds;
+    constructor(views, streams, sessions, tokens, embeds) {
+        this.views = views;
+        this.streams = streams;
+        this.sessions = sessions;
+        this.tokens = tokens;
+        this.embeds = embeds;
+    }
+    async contributions(principal) {
+        requireUser(principal);
+        return { items: await this.views.platformContributions() };
+    }
+    async arrangement(principal) {
+        requireUser(principal);
+        return { slots: await this.views.platformArrangementView() };
+    }
+    async view(principal, { plugin, id }, q) {
+        const p = requireUser(principal);
+        const view = await this.views.render({
+            scope: "platform",
+            accountId: p.account.id,
+            plugin,
+            id,
+            locale: q.locale,
+        });
+        return { view };
+    }
+    async action(principal, { plugin, id }, body) {
+        const p = requireUser(principal);
+        return this.views.act({ scope: "platform", accountId: p.account.id, plugin, id, locale: body.locale }, {
+            actionId: body.actionId,
+            ...(body.payload !== undefined && { payload: body.payload }),
+            ...(body.answer !== undefined && { answer: body.answer }),
+        });
+    }
+    async embedToken(principal, { plugin, id }) {
+        const p = requireUser(principal);
+        const target = await this.views.embed({
+            scope: "platform",
+            accountId: p.account.id,
+            plugin,
+            id,
+        });
+        const { token, expiresAt } = this.embeds.issue({
+            plugin: target.plugin,
+            scope: "platform",
+            accountId: p.account.id,
+            role: "superAdmin",
+            contribution: target.contribution,
+        });
+        return {
+            token,
+            src: embedSrc(target.plugin, target.path),
+            expiresAt: expiresAt.toISOString(),
+            expiresIn: EMBED_TOKEN_TTL_SECONDS,
+        };
+    }
+    /** The platform refresh stream: written on the raw response (`reply.hijack()`) like the org one. */
+    async stream(principal, req, reply) {
+        const p = requireUser(principal);
+        const res = reply.raw;
+        const handle = await this.streams.open({
+            scope: "platform",
+            viewerAccountId: p.account.id,
+            credential: credentialCheck(p, BEARER_RE.exec(req.headers.authorization ?? "")?.[1], {
+                sessions: this.sessions,
+                tokens: this.tokens,
+            }),
+        }, {
+            write: (chunk) => {
+                res.write(chunk);
+            },
+            backlog: () => res.writableLength,
+            end: () => {
+                res.end();
+            },
+            abort: () => {
+                res.destroy();
+            },
+        });
+        reply.hijack();
+        res.on("close", () => handle.close());
+        if (res.destroyed || !res.socket || res.socket.destroyed) {
+            handle.close();
+            res.destroy();
+            return;
+        }
+        res.writeHead(200, {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache",
+            "x-accel-buffering": "no",
+            connection: "keep-alive",
+        });
+        res.flushHeaders();
+        handle.begin();
+    }
+};
+__decorate([
+    Get("contributions"),
+    __param(0, CurrentPrincipal())
+], AdminUiController.prototype, "contributions", null);
+__decorate([
+    Get("arrangement"),
+    __param(0, CurrentPrincipal())
+], AdminUiController.prototype, "arrangement", null);
+__decorate([
+    Get("views/:plugin/:id"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(AdminUiContributionParamsDto)),
+    __param(2, ZQuery(AdminUiViewQueryDto))
+], AdminUiController.prototype, "view", null);
+__decorate([
+    Post("actions/:plugin/:id"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(AdminUiContributionParamsDto)),
+    __param(2, ZBody(AdminUiActionBodyDto))
+], AdminUiController.prototype, "action", null);
+__decorate([
+    Post("embeds/:plugin/:id/token"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(AdminUiContributionParamsDto))
+], AdminUiController.prototype, "embedToken", null);
+__decorate([
+    Get("stream"),
+    __param(0, CurrentPrincipal()),
+    __param(1, Req()),
+    __param(2, Res())
+], AdminUiController.prototype, "stream", null);
+AdminUiController = __decorate([
+    Controller("api/v1/admin/ui"),
+    SuperAdmin(),
+    __param(0, Inject(UiViews)),
+    __param(1, Inject(OrgUiStreams)),
+    __param(2, Inject(SessionService)),
+    __param(3, Inject(ApiTokenService)),
+    __param(4, Inject(EmbedTokens))
+], AdminUiController);
+export { AdminUiController };

package/dist/ui/arrangement.d.ts

@@ -0,0 +1,65 @@
+import { type UiSlotId } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import type { UiContributionItem } from "./views.js";
+export type UiListEntry = {
+    hidden: string[];
+    order: string[];
+};
+export type UiUseEntry = {
+    use: string | null;
+};
+/** One slot's entry: `{ hidden, order }` on a list slot, `{ use }` on a single slot. */
+export type UiArrangementEntry = UiListEntry | UiUseEntry;
+export type UiArrangement = Partial<Record<UiSlotId, UiArrangementEntry>>;
+/** Whether a slot is a single (replaceable) slot. */
+export declare const isSingle: (slot: UiSlotId) => boolean;
+export declare const UiArrangementSchema: z.ZodType<UiArrangement>;
+/** The slots an org arranges: every arrangeable slot but the platform's own. */
+export declare const ORG_ARRANGEABLE: readonly UiSlotId[];
+/** An org's patch: a slot's entry replaces the stored one, null removes it. */
+export declare const OrgUiArrangementPatchSchema: z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown>>;
+/** A deployment patch: like {@link OrgUiArrangementPatchSchema} over every arrangeable slot. */
+export declare const UiArrangementPatchSchema: z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", UiArrangementEntry | null>>, unknown>>;
+/** Merges a per-slot patch into the stored arrangement (null removes the slot's entry). */
+export declare function mergeArrangement(current: UiArrangement | undefined, patch: Partial<Record<UiSlotId, UiArrangementEntry | null>>): UiArrangement;
+/**
+ * The list entry that applies to a slot: the org's if it arranged the slot, else the platform's
+ * (a `use` entry, which only a single slot stores, reads as none).
+ */
+export declare function effectiveEntry(org: UiArrangement | undefined, platform: UiArrangement, slot: UiSlotId): {
+    entry: UiListEntry;
+    source: "org" | "platform" | "none";
+};
+/**
+ * The winner of a single slot (client extensions spec §6.3): the org's entry if it has one, else
+ * the platform's, else none. No entry or `use: null` is the built-in (null); a `use` naming a key
+ * not in `available` (extension off in the org, contribution dropped, the viewer's role below the
+ * slot's) is the built-in too, never the other level's pick. A list slot, or an entry that is not
+ * a `use` entry, has no winner.
+ */
+export declare function resolveSingleSlot(slot: UiSlotId, orgEntry: UiArrangementEntry | undefined, platformEntry: UiArrangementEntry | undefined, available: ReadonlySet<string>): string | null;
+/** The `use` stored for a single slot: the org's entry if it has one, else the platform's. */
+export declare function storedUse(org: UiArrangement | undefined, platform: UiArrangement, slot: UiSlotId): {
+    use: string | null;
+    followsPlatform: boolean;
+};
+/** The arrangement key of a contribution: `<plugin>/<id>`. */
+export declare const keyOf: (i: {
+    plugin: string;
+    id: string;
+}) => string;
+/**
+ * Orders the items of one slot (hidden ones stay in place): grouped by anchor in the slot's anchor
+ * order, also without an entry (the lists match what the page renders per anchor); within a group
+ * the keys of `entry.order` come first in that order, the rest in base order. Unknown keys are
+ * ignored, so an order never moves an item across anchors.
+ */
+export declare function orderItems(items: UiContributionItem[], entry: UiListEntry): UiContributionItem[];
+/** {@link orderItems} without the hidden keys. */
+export declare function arrange(items: UiContributionItem[], entry: UiListEntry): UiContributionItem[];
+/**
+ * Applies the per-slot entries to a mixed list: each slot's items are arranged and written back
+ * into the positions that slot occupied (a slot without an entry: its base order, grouped by
+ * anchor).
+ */
+export declare function arrangeBySlot(items: UiContributionItem[], entryOf: (slot: UiSlotId) => UiListEntry): UiContributionItem[];

package/dist/ui/arrangement.js

@@ -0,0 +1,171 @@
+import { UI_ARRANGEABLE_SLOTS, UI_CONTRIBUTION_KEY_RE, UI_SINGLE_SLOTS, uiSlot, } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/**
+ * Arrangement of UI slots (UI slots spec §5, client extensions spec §6.3): per list slot, which
+ * contributions are hidden and in which order; per single slot, which contribution replaces the
+ * built-in (`use`, null = the built-in). "Hidden" means not listed and `use` only picks what is
+ * listed: the access gate never reads an arrangement, so a contribution's view, action and embed
+ * routes keep working for an allowed role whatever the arrangement says.
+ */
+const Key = z.string().regex(UI_CONTRIBUTION_KEY_RE, "must be a contribution key <plugin>/<id>");
+const LIST_MAX = 200;
+/**
+ * A list slot's entry: the keys hidden and the keys ordered first. The refusals name the slot and
+ * what it takes (actionable for an admin and the Platform tool's model).
+ */
+const listEntrySchema = (slot) => {
+    const keys = z
+        .array(Key, {
+        error: (iss) => iss.input === undefined
+            ? `${slot} is a list slot: give an array of contribution keys <plugin>/<id>`
+            : undefined,
+    })
+        .max(LIST_MAX);
+    return z.strictObject({ hidden: keys, order: keys }, {
+        error: (iss) => iss.code === "unrecognized_keys"
+            ? `${slot} is a list slot: give { hidden, order }; use is only for the single slots (${UI_SINGLE_SLOTS.join(", ")})`
+            : undefined,
+    });
+};
+/** A single slot's entry: the contribution that replaces the built-in, or null for the built-in. */
+const useEntrySchema = (slot) => z.strictObject({
+    use: z.union([Key, z.null()], {
+        error: (iss) => iss.input === undefined
+            ? `${slot} needs use: a contribution key <plugin>/<id>, or null for the built-in`
+            : undefined,
+    }),
+}, {
+    error: (iss) => iss.code === "unrecognized_keys"
+        ? `${slot} is a single slot: give { use } (a contribution key <plugin>/<id>, or null for the built-in); hidden and order are only for list slots`
+        : undefined,
+});
+/** Whether a slot is a single (replaceable) slot. */
+export const isSingle = (slot) => UI_SINGLE_SLOTS.includes(slot);
+/**
+ * An object over `slots`, each optional and of its kind's entry (nullable in a patch); unknown
+ * slots are refused, and so are `use` on a list slot and `hidden` / `order` on a single slot (400
+ * `validation_failed` on the settings routes).
+ */
+function arrangementShape(slots, nullable) {
+    const shape = {};
+    for (const slot of slots) {
+        const entry = isSingle(slot) ? useEntrySchema(slot) : listEntrySchema(slot);
+        shape[slot] = (nullable ? entry.nullable() : entry).optional();
+    }
+    return z.object(shape).strict();
+}
+export const UiArrangementSchema = arrangementShape(UI_ARRANGEABLE_SLOTS, false);
+/** The slots an org arranges: every arrangeable slot but the platform's own. */
+export const ORG_ARRANGEABLE = UI_ARRANGEABLE_SLOTS.filter((s) => s !== "platform.page");
+/** An org's patch: a slot's entry replaces the stored one, null removes it. */
+export const OrgUiArrangementPatchSchema = arrangementShape(ORG_ARRANGEABLE, true);
+/** A deployment patch: like {@link OrgUiArrangementPatchSchema} over every arrangeable slot. */
+export const UiArrangementPatchSchema = arrangementShape(UI_ARRANGEABLE_SLOTS, true);
+/** Merges a per-slot patch into the stored arrangement (null removes the slot's entry). */
+export function mergeArrangement(current, patch) {
+    const merged = { ...current };
+    for (const [slot, entry] of Object.entries(patch)) {
+        if (entry === null)
+            delete merged[slot];
+        else if (entry !== undefined)
+            merged[slot] = entry;
+    }
+    return merged;
+}
+const NONE = { hidden: [], order: [] };
+const asList = (e) => ("hidden" in e ? e : NONE);
+/**
+ * The list entry that applies to a slot: the org's if it arranged the slot, else the platform's
+ * (a `use` entry, which only a single slot stores, reads as none).
+ */
+export function effectiveEntry(org, platform, slot) {
+    const o = org?.[slot];
+    if (o !== undefined)
+        return { entry: asList(o), source: "org" };
+    const p = platform[slot];
+    if (p !== undefined)
+        return { entry: asList(p), source: "platform" };
+    return { entry: NONE, source: "none" };
+}
+/**
+ * The winner of a single slot (client extensions spec §6.3): the org's entry if it has one, else
+ * the platform's, else none. No entry or `use: null` is the built-in (null); a `use` naming a key
+ * not in `available` (extension off in the org, contribution dropped, the viewer's role below the
+ * slot's) is the built-in too, never the other level's pick. A list slot, or an entry that is not
+ * a `use` entry, has no winner.
+ */
+export function resolveSingleSlot(slot, orgEntry, platformEntry, available) {
+    if (!isSingle(slot))
+        return null;
+    const entry = orgEntry ?? platformEntry;
+    if (entry === undefined || !("use" in entry) || entry.use === null)
+        return null;
+    return available.has(entry.use) ? entry.use : null;
+}
+/** The `use` stored for a single slot: the org's entry if it has one, else the platform's. */
+export function storedUse(org, platform, slot) {
+    const o = org?.[slot];
+    const e = o ?? platform[slot];
+    return {
+        use: e !== undefined && "use" in e ? e.use : null,
+        followsPlatform: o === undefined,
+    };
+}
+/** The arrangement key of a contribution: `<plugin>/<id>`. */
+export const keyOf = (i) => `${i.plugin}/${i.id}`;
+/**
+ * Orders the items of one slot (hidden ones stay in place): grouped by anchor in the slot's anchor
+ * order, also without an entry (the lists match what the page renders per anchor); within a group
+ * the keys of `entry.order` come first in that order, the rest in base order. Unknown keys are
+ * ignored, so an order never moves an item across anchors.
+ */
+export function orderItems(items, entry) {
+    const anchors = items[0] === undefined ? undefined : uiSlot(items[0].slot)?.anchors;
+    const groupOf = (i) => anchors === undefined ? 0 : Math.max(0, anchors.indexOf(i.after ?? anchors[0] ?? ""));
+    const rank = new Map(entry.order.map((k, n) => [k, n]));
+    return items
+        .map((item, base) => ({ item, base }))
+        .sort((a, b) => {
+        const g = groupOf(a.item) - groupOf(b.item);
+        if (g !== 0)
+            return g;
+        const ra = rank.get(keyOf(a.item));
+        const rb = rank.get(keyOf(b.item));
+        if (ra !== undefined && rb !== undefined)
+            return ra - rb;
+        if (ra !== undefined)
+            return -1;
+        if (rb !== undefined)
+            return 1;
+        return a.base - b.base;
+    })
+        .map((x) => x.item);
+}
+/** {@link orderItems} without the hidden keys. */
+export function arrange(items, entry) {
+    const hidden = new Set(entry.hidden);
+    return orderItems(items, entry).filter((i) => !hidden.has(keyOf(i)));
+}
+/**
+ * Applies the per-slot entries to a mixed list: each slot's items are arranged and written back
+ * into the positions that slot occupied (a slot without an entry: its base order, grouped by
+ * anchor).
+ */
+export function arrangeBySlot(items, entryOf) {
+    const bySlot = new Map();
+    items.forEach((i, n) => {
+        const at = bySlot.get(i.slot);
+        if (at)
+            at.push(n);
+        else
+            bySlot.set(i.slot, [n]);
+    });
+    const out = [...items];
+    for (const [slot, at] of bySlot) {
+        const arranged = arrange(at.map((n) => items[n]), entryOf(slot));
+        at.forEach((n, j) => {
+            out[n] = arranged[j];
+        });
+    }
+    return out.filter((i) => i !== undefined);
+}

package/dist/ui/embed-token.d.ts

@@ -1,4 +1,4 @@
-import type { EmbedClaims } from "@capybara-hq/plugin-sdk";
+import type { EmbedClaims, OrgEmbedClaims, PlatformEmbedClaims } from "@capybara-hq/plugin-sdk";
 import type { Keyring } from "../ctx/secrets.js";
 /** 嵌入令牌的有效期（秒）。网页在过期前 60 秒续期。 */
 export declare const EMBED_TOKEN_TTL_SECONDS = 300;
@@ -22,7 +22,7 @@ export declare class EmbedTokens {
     private readonly keys;
     constructor(keyring: Keyring, now?: () => number);
     /** 签发：`exp` = 现在 + {@link EMBED_TOKEN_TTL_SECONDS}。 */
-    issue(c: Omit<EmbedClaims, "exp">): {
+    issue(c: Omit<OrgEmbedClaims, "exp"> | Omit<PlatformEmbedClaims, "exp">): {
         token: string;
         claims: EmbedClaims;
         expiresAt: Date;