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

package/dist/tools/builtins/sandbox/task-stop.js

@@ -1,7 +1,7 @@
 import { rootsOf, ToolError } from "@capybara-hq/plugin-sdk";
 import { decodeTail, tailCommand } from "../../../background/session.js";
 import { clip, display, mapSandboxError, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
-import { onTaskInstance, ownedTask, recheckEnvironment, statusLine, taskEnv, } from "./task-output.js";
+import { onTaskInstance, ownedTask, recheckDevice, statusLine, taskEnv, } from "./task-output.js";
 /** The time limit of reading a stopped task's last lines. */
 const TAIL_EXEC_TIMEOUT_MS = 10_000;
 const SPEC = {
@@ -84,7 +84,7 @@ export function taskStopTool(deps) {
             const { task_id } = input;
             const env = await taskEnv(deps, ctx);
             const task = await ownedTask(env, ctx, task_id);
-            await recheckEnvironment(env, ctx);
+            await recheckDevice(env, ctx);
             if (task.status !== "running") {
                 return ended(env, task, "had already finished", ctx.signal);
             }

package/dist/tools/builtins/sandbox/write.js

@@ -46,10 +46,10 @@ export function sandboxWriteTool(deps) {
             const data = new TextEncoder().encode(input.content);
             checkPathShape(input.file_path, "file_path");
             let path = "";
-            const { value, notices } = await inSandbox(deps, ctx, ({ environmentId, h, roots, p, signal }) => {
+            const { value, notices } = await inSandbox(deps, ctx, ({ deviceId, h, roots, p, signal }) => {
                 path = checkWritable(input.file_path, roots);
                 // stat, read the previous content, write: one holder at a time per file
-                return withPathLease(deps, { environmentId }, path, signal, async (signal) => {
+                return withPathLease(deps, { deviceId }, path, signal, async (signal) => {
                     const st = await p.stat(h, path, signal);
                     if (st?.isDir)
                         throw new ToolError(isDirectory(path));

package/dist/tools/builtins/skill-load.d.ts

@@ -8,7 +8,7 @@ import { type SandboxToolDeps } from "./sandbox/common.js";
  * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
  * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
  * (the result names the version). A skill with other files is copied whole into the conversation's
- * environment at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
+ * device at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
  * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
  * the shared file system). Without a sandbox provider only the body is given, with a note that
  * scripts are unavailable.

package/dist/tools/builtins/skill-load.js

@@ -14,7 +14,7 @@ import { clip, display, inSandbox, sandboxBaseTimeoutMs, sandboxConversationOf,
  * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
  * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
  * (the result names the version). A skill with other files is copied whole into the conversation's
- * environment at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
+ * device at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
  * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
  * the shared file system). Without a sandbox provider only the body is given, with a note that
  * scripts are unavailable.
@@ -49,7 +49,7 @@ const SPEC = {
     description: "Load a skill from the skills list: returns the skill's instructions " +
         "(its SKILL.md) and the list of its files. Call it before starting a task that matches a " +
         "skill's description, then follow the returned instructions. If the skill has scripts or other " +
-        "files, they are copied read-only to <name>@<version-id>/ in the skills directory of this environment; run scripts " +
+        "files, they are copied read-only to <name>@<version-id>/ in the skills directory of this device; run scripts " +
         "there with an interpreter (sh, python3, node). Call it again when the skills list changes. Pass args when the task gives the skill arguments (they replace " +
         "$ARGUMENTS and $1, $2… in the instructions). Do not use it for skills that are not in the list.",
     inputSchema: {

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;

package/dist/ui/embed-token.js

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