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

package/dist/tools/oauth/tokens.js

@@ -68,20 +68,11 @@ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** RFC 6749 §5.2 形式的错误码（只有这种串才写进日志 / 错误，不回显对方任意文本）。 */
 const OAUTH_ERROR_RE = /^[a-z][a-z0-9_]{0,63}$/;
 /**
- * Calls the token endpoint (RFC 6749 §3.2), sending client_id / secret per the client's auth method
- * (Basic form-encodes them first, §2.3.1).
- * - 400 / 401 with a parsable RFC 6749 `error` code -> OAuthGrantError.
- * - 200 with `ok: false` (Slack reports every error this way), or with an `error` code and no
- *   `access_token` -> OAuthGrantError with that code (`ok: false` wins over an `access_token`); a
- *   transient code (`temporarily_unavailable`, `server_error`, Slack's `ratelimited`, ...) or no
- *   parsable code -> OAuthUnavailable.
- * - Everything else (network error, timeout, 429, 408, 403 and other 4xx, a 4xx without a code,
- *   5xx, 3xx, a malformed body) -> OAuthUnavailable: a gateway's rate limit or a WAF block is not a
- *   dead credential.
- * - A `token_type` other than Bearer / `user` / `opts.tokenTypes` -> OAuthGrantError
- *   `unsupported_token_type`; an accepted one is stored as `Bearer`.
+ * The headers and form of a token request (RFC 6749 §3.2): client_id / secret per the client's
+ * auth method (Basic form-encodes them first, §2.3.1; otherwise `client_id`, plus
+ * `client_secret` for `client_secret_post`). Empty parameters are left out.
  */
-export async function tokenRequest(client, params, http, opts = {}) {
+export function tokenRequestInit(client, params) {
     const form = new URLSearchParams();
     for (const [k, v] of Object.entries(params))
         if (v !== undefined && v !== "")
@@ -91,8 +82,7 @@ export async function tokenRequest(client, params, http, opts = {}) {
         accept: "application/json",
     };
     if (client.authMethod === "client_secret_basic" && client.clientSecret !== undefined) {
-        const enc = (s) => encodeURIComponent(s).replace(/%20/g, "+");
-        headers.authorization = `Basic ${Buffer.from(`${enc(client.clientId)}:${enc(client.clientSecret)}`).toString("base64")}`;
+        headers.authorization = basicClientAuth(client.clientId, client.clientSecret);
     }
     else {
         form.set("client_id", client.clientId);
@@ -100,6 +90,46 @@ export async function tokenRequest(client, params, http, opts = {}) {
             form.set("client_secret", client.clientSecret);
         }
     }
+    return { headers, body: form };
+}
+/** The form encoding of a Basic client credential part (RFC 6749 §2.3.1). */
+export const formEncode = (s) => encodeURIComponent(s).replace(/%20/g, "+");
+/** The `Authorization` value of `client_secret_basic` (both parts form-encoded first). */
+export const basicClientAuth = (clientId, clientSecret) => `Basic ${Buffer.from(`${formEncode(clientId)}:${formEncode(clientSecret)}`).toString("base64")}`;
+/**
+ * The refusal code of a token endpoint answer, or null when it is not a refusal (the one parser of
+ * token refusals): a 400 / 401 whose JSON body has an RFC 6749-shaped `error`, or a 200 whose body
+ * carries `ok: false` (Slack) or an `error` and no `access_token`, with a code that is not
+ * transient. Only codes matching the RFC 6749 shape are returned, never other text of the body.
+ */
+export function parseTokenRefusal(status, body) {
+    const code = isObj(body) ? body.error : undefined;
+    const shaped = typeof code === "string" && OAUTH_ERROR_RE.test(code) ? code : null;
+    if (status === 400 || status === 401)
+        return shaped;
+    if (status !== 200 || !isObj(body))
+        return null;
+    if (body.ok === false || (body.access_token === undefined && body.error !== undefined)) {
+        return shaped !== null && !TRANSIENT_ERRORS.has(shaped) ? shaped : null;
+    }
+    return null;
+}
+/**
+ * Calls the token endpoint (RFC 6749 §3.2), sending client_id / secret per the client's auth method
+ * (Basic form-encodes them first, §2.3.1).
+ * - 400 / 401 with a parsable RFC 6749 `error` code -> OAuthGrantError.
+ * - 200 with `ok: false` (Slack reports every error this way), or with an `error` code and no
+ *   `access_token` -> OAuthGrantError with that code (`ok: false` wins over an `access_token`); a
+ *   transient code (`temporarily_unavailable`, `server_error`, Slack's `ratelimited`, ...) or no
+ *   parsable code -> OAuthUnavailable.
+ * - Everything else (network error, timeout, 429, 408, 403 and other 4xx, a 4xx without a code,
+ *   5xx, 3xx, a malformed body) -> OAuthUnavailable: a gateway's rate limit or a WAF block is not a
+ *   dead credential.
+ * - A `token_type` other than Bearer / `user` / `opts.tokenTypes` -> OAuthGrantError
+ *   `unsupported_token_type`; an accepted one is stored as `Bearer`.
+ */
+export async function tokenRequest(client, params, http, opts = {}) {
+    const { headers, body: form } = tokenRequestInit(client, params);
     let res;
     try {
         res = await oauthFetch(client.tokenEndpoint, { method: "POST", headers, body: form }, http);
@@ -116,18 +146,13 @@ export async function tokenRequest(client, params, http, opts = {}) {
     catch {
         body = undefined;
     }
-    if (res.status === 400 || res.status === 401) {
-        const code = isObj(body) ? body.error : undefined;
-        if (typeof code === "string" && OAUTH_ERROR_RE.test(code))
-            throw new OAuthGrantError(code);
-    }
+    const refusal = parseTokenRefusal(res.status, body);
+    if (refusal !== null)
+        throw new OAuthGrantError(refusal);
     if (res.status !== 200 || !isObj(body))
         throw new OAuthUnavailable();
+    // an error body without a usable code (or a transient one): unavailable, not a refusal
     if (body.ok === false || (body.access_token === undefined && body.error !== undefined)) {
-        const code = body.error;
-        if (typeof code === "string" && OAUTH_ERROR_RE.test(code) && !TRANSIENT_ERRORS.has(code)) {
-            throw new OAuthGrantError(code);
-        }
         throw new OAuthUnavailable();
     }
     const { access_token, refresh_token, expires_in, token_type, scope } = body;

package/dist/tools/pipeline.js

@@ -207,9 +207,10 @@ let ToolPipeline = class ToolPipeline {
             },
             effective,
             switches,
-            inlineViews: (plugin) => new Set((host?.current(plugin)?.manifest.ui ?? [])
-                .filter((c) => c.place === "inline" && c.aliasOf === undefined)
-                .map((c) => c.id)),
+            inlineViews: (plugin) => new Set((host?.current(plugin)?.ui ?? [])
+                .filter((r) => r.slot.id === "conversation.tool-result.card" &&
+                r.contribution.aliasOf === undefined)
+                .map((r) => r.contribution.id)),
             onToolsChanged: (orgId, connectorId) => {
                 void drift?.onToolsChanged(orgId, connectorId);
             },

package/dist/tools/registry.d.ts

@@ -14,7 +14,7 @@ export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
 export { canonicalJson } from "./canonical-json.js";
 /**
  * What a tool's `unavailable` is asked with: the org, and for a run's listing the root
- * conversation (`conversationId`; the sandbox tools follow its environment, ruling R8), whether
+ * conversation (`conversationId`; the sandbox tools follow its device, ruling R8), whether
  * the run is an eval replay (`replay`: its tool calls are never executed), and a `memo` shared by
  * the tools of one listing (one answer per question per listing).
  */
@@ -346,7 +346,7 @@ export declare class ToolRegistry {
         forkChild?: boolean;
         /**
          * The root conversation of the run (a sub-agent's tree root): tools whose availability
-         * depends on the conversation's environment (the sandbox tools) are listed by it.
+         * depends on the conversation's device (the sandbox tools) are listed by it.
          */
         sandboxConversationId?: string;
         /** An eval replay's listing: its calls are never executed (the sandbox tools are listed). */

package/dist/tools/tools.module.js

@@ -9,7 +9,7 @@ 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 { EnvironmentsModule } from "../environments/environments.module.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";
@@ -59,9 +59,9 @@ ToolsModule = __decorate([
             OrgLockModule,
             // the `Agent` tool's dispatch
             SubagentsModule,
-            // the builtin sandbox and skill tools run in the conversation's environment
+            // the builtin sandbox and skill tools run in the conversation's device
             SandboxModule,
-            EnvironmentsModule,
+            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

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,74 @@
+import { type UiSlotId } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import type { UiContributionItem } from "./views.js";
+export declare const UiArrangementEntrySchema: z.ZodObject<{
+    hidden: z.ZodArray<z.ZodString>;
+    order: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type UiArrangementEntry = z.infer<typeof UiArrangementEntrySchema>;
+export declare const UiArrangementSchema: z.ZodRecord<z.ZodEnum<{
+    "agent.detail.section": "agent.detail.section";
+    "conversation.panel": "conversation.panel";
+    "conversation.properties.section": "conversation.properties.section";
+    "conversation.tool-result.card": "conversation.tool-result.card";
+    "file.preview": "file.preview";
+    "org.page": "org.page";
+    "org.settings.section": "org.settings.section";
+    "platform.page": "platform.page";
+}> & z.core.$partial, z.ZodObject<{
+    hidden: z.ZodArray<z.ZodString>;
+    order: z.ZodArray<z.ZodString>;
+}, z.core.$strict>>;
+export type UiArrangement = z.infer<typeof UiArrangementSchema>;
+/** 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.ZodRecord<z.ZodEnum<{
+    "agent.detail.section": "agent.detail.section";
+    "conversation.panel": "conversation.panel";
+    "conversation.properties.section": "conversation.properties.section";
+    "conversation.tool-result.card": "conversation.tool-result.card";
+    "file.preview": "file.preview";
+    "org.page": "org.page";
+    "org.settings.section": "org.settings.section";
+    "platform.page": "platform.page";
+}> & z.core.$partial, z.ZodNullable<z.ZodObject<{
+    hidden: z.ZodArray<z.ZodString>;
+    order: z.ZodArray<z.ZodString>;
+}, z.core.$strict>>>;
+/** A deployment patch: like {@link OrgUiArrangementPatchSchema} over every arrangeable slot. */
+export declare const UiArrangementPatchSchema: z.ZodRecord<z.ZodEnum<{
+    "agent.detail.section": "agent.detail.section";
+    "conversation.panel": "conversation.panel";
+    "conversation.properties.section": "conversation.properties.section";
+    "conversation.tool-result.card": "conversation.tool-result.card";
+    "file.preview": "file.preview";
+    "org.page": "org.page";
+    "org.settings.section": "org.settings.section";
+    "platform.page": "platform.page";
+}> & z.core.$partial, z.ZodNullable<z.ZodObject<{
+    hidden: z.ZodArray<z.ZodString>;
+    order: z.ZodArray<z.ZodString>;
+}, z.core.$strict>>>;
+/** 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 entry that applies to a slot: the org's if it arranged the slot, else the platform's. */
+export declare function effectiveEntry(org: UiArrangement | undefined, platform: UiArrangement, slot: UiSlotId): {
+    entry: UiArrangementEntry;
+    source: "org" | "platform" | "none";
+};
+/**
+ * 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: UiArrangementEntry): UiContributionItem[];
+/** {@link orderItems} without the hidden keys. */
+export declare function arrange(items: UiContributionItem[], entry: UiArrangementEntry): 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) => UiArrangementEntry): UiContributionItem[];

package/dist/ui/arrangement.js

@@ -0,0 +1,98 @@
+import { UI_ARRANGEABLE_SLOTS, UI_CONTRIBUTION_KEY_RE, uiSlot, } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/**
+ * Arrangement of UI slots (UI slots spec §5): per slot, which contributions are hidden and in
+ * which order. "Hidden" means not listed: the access gate never reads an arrangement, so a hidden
+ * contribution's view, action and embed routes keep working for an allowed role.
+ */
+const Key = z.string().regex(UI_CONTRIBUTION_KEY_RE);
+const LIST_MAX = 200;
+export const UiArrangementEntrySchema = z
+    .object({ hidden: z.array(Key).max(LIST_MAX), order: z.array(Key).max(LIST_MAX) })
+    .strict();
+export const UiArrangementSchema = z.partialRecord(z.enum(UI_ARRANGEABLE_SLOTS), UiArrangementEntrySchema);
+/** 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 = z.partialRecord(z.enum(ORG_ARRANGEABLE), UiArrangementEntrySchema.nullable());
+/** A deployment patch: like {@link OrgUiArrangementPatchSchema} over every arrangeable slot. */
+export const UiArrangementPatchSchema = z.partialRecord(z.enum(UI_ARRANGEABLE_SLOTS), UiArrangementEntrySchema.nullable());
+/** 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: [] };
+/** The entry that applies to a slot: the org's if it arranged the slot, else the platform's. */
+export function effectiveEntry(org, platform, slot) {
+    const o = org?.[slot];
+    if (o !== undefined)
+        return { entry: o, source: "org" };
+    const p = platform[slot];
+    if (p !== undefined)
+        return { entry: p, source: "platform" };
+    return { entry: NONE, source: "none" };
+}
+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;