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

package/dist/tools/credentials.d.ts

@@ -119,6 +119,26 @@ export declare class Credentials {
      * 都会更新写入时间），最多 `limit` 个。漂移检查用它挑个人凭据型连接器的凭据。
      */
     personalHolders(orgId: string, connectorId: string, limit: number): Promise<string[]>;
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a connector's credentials,
+     * the `updated_at` of its OAuth client row, its org credential row and, given `accountId`, that
+     * member's row (ISO), never a value. Reads no secret.
+     */
+    checkRevision(orgId: string, connectorId: string, accountId: string | null): Promise<string>;
+    /**
+     * For setup checks (setup guides v2 §10.8), never refreshing or writing anything: every stored
+     * credential value of a connector (decrypted: the OAuth client secret and DCR registration
+     * token, the org credential, every member's access and refresh tokens or static values) that a
+     * check result is redacted by, with the forms they are sent in (what `injectionSecrets` covers
+     * for a tool call: the Basic header value, its base64 token and decoded `user:pass`, the
+     * `encodeURIComponent` forms; for the client also the `client_secret_basic` header the token
+     * request sends and the raw `id:secret`), and the stored OAuth client id (null without a
+     * client). Never echo the values; a plugin check gets only a manual client's id.
+     */
+    checkMaterial(orgId: string, connectorId: string): Promise<{
+        secrets: string[];
+        clientId: string | null;
+    }>;
     /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
     status(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string): Promise<"connected" | "missing">;
     /** 返回本次请求要注入的头 / 查询参数；缺凭据抛 CredentialMissing。 */

package/dist/tools/credentials.js

@@ -17,7 +17,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import { KERNEL_LOGGER, KEYRING, REDIS } from "../infra/tokens.js";
 import { oauthHttpOptions } from "./oauth/discovery.js";
-import { OAuthReconnectRequired, OAuthTokens, } from "./oauth/tokens.js";
+import { basicClientAuth, OAuthReconnectRequired, OAuthTokens, } from "./oauth/tokens.js";
 import { injectionSecrets } from "./redact.js";
 export const isOAuth = (auth) => auth.type === "oauth_code" || auth.type === "oauth_client";
 /** 缺凭据：只带连接器 id 与归属，绝不带值。 */
@@ -239,6 +239,95 @@ let Credentials = class Credentials {
       LIMIT ${limit}`.execute(this.db.db);
         return rows.rows.map((r) => r.account_id);
     }
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a connector's credentials,
+     * the `updated_at` of its OAuth client row, its org credential row and, given `accountId`, that
+     * member's row (ISO), never a value. Reads no secret.
+     */
+    async checkRevision(orgId, connectorId, accountId) {
+        const keys = [clientKey(connectorId), orgKey(connectorId)];
+        if (accountId !== null)
+            keys.push(userKey(connectorId, accountId));
+        const rows = await this.db
+            .selectFrom("secrets")
+            .select(["key", "updated_at"])
+            .where("namespace", "=", NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "in", keys)
+            .execute();
+        const at = new Map(rows.map((r) => [r.key, new Date(r.updated_at).toISOString()]));
+        return keys.map((k) => at.get(k) ?? "-").join("|");
+    }
+    /**
+     * For setup checks (setup guides v2 §10.8), never refreshing or writing anything: every stored
+     * credential value of a connector (decrypted: the OAuth client secret and DCR registration
+     * token, the org credential, every member's access and refresh tokens or static values) that a
+     * check result is redacted by, with the forms they are sent in (what `injectionSecrets` covers
+     * for a tool call: the Basic header value, its base64 token and decoded `user:pass`, the
+     * `encodeURIComponent` forms; for the client also the `client_secret_basic` header the token
+     * request sends and the raw `id:secret`), and the stored OAuth client id (null without a
+     * client). Never echo the values; a plugin check gets only a manual client's id.
+     */
+    async checkMaterial(orgId, connectorId) {
+        const prefix = orgKey(connectorId).slice(0, -"org".length);
+        const rows = await this.db
+            .selectFrom("secrets")
+            .select("key")
+            .where("namespace", "=", NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where(sql `left(key, ${prefix.length})`, "=", prefix)
+            .execute();
+        const secrets = new Set();
+        const push = (...vs) => {
+            for (const v of vs) {
+                if (typeof v !== "string" || v === "")
+                    continue;
+                // the value and the forms an injection carries it in (`Bearer`, query, percent-encoded)
+                for (const s of injectionSecrets({ headers: { a: `Bearer ${v}` }, query: { q: v } })) {
+                    secrets.add(s);
+                }
+            }
+        };
+        const pushBasic = (user, password) => {
+            const header = `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+            for (const s of injectionSecrets({ headers: { a: header } }))
+                secrets.add(s);
+        };
+        let clientId = null;
+        for (const r of rows) {
+            const v = (await this.readJson(orgId, r.key, connectorId));
+            if (v === null || typeof v !== "object")
+                continue;
+            if (r.key === clientKey(connectorId)) {
+                // the client id is not a secret (a plugin check gets it); the secret and DCR token are
+                if (typeof v.clientId === "string")
+                    clientId = v.clientId;
+                push(v.clientSecret, v.registration?.accessToken);
+                if (typeof v.clientId === "string" && typeof v.clientSecret === "string") {
+                    // as the token request sends it (both parts form-encoded), and as typed
+                    const header = basicClientAuth(v.clientId, v.clientSecret);
+                    for (const s of injectionSecrets({ headers: { a: header } }))
+                        secrets.add(s);
+                    pushBasic(v.clientId, v.clientSecret);
+                }
+            }
+            else if (typeof v.access_token === "string") {
+                push(v.access_token, v.refresh_token);
+            }
+            else {
+                push(v.token, v.password);
+                if (typeof v.username === "string" && typeof v.password === "string") {
+                    pushBasic(v.username, v.password);
+                }
+                if (typeof v.headers === "object" && v.headers !== null) {
+                    const headers = Object.fromEntries(Object.entries(v.headers).filter((e) => typeof e[1] === "string"));
+                    for (const s of injectionSecrets({ headers }))
+                        secrets.add(s);
+                }
+            }
+        }
+        return { secrets: [...secrets], clientId };
+    }
     /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
     async status(orgId, connectorId, auth, accountId) {
         if (auth.type === "none")

package/dist/tools/oauth/tokens.d.ts

@@ -75,6 +75,26 @@ export interface TokenRequestOptions {
     /** More `token_type` values to accept as bearer tokens (`auth.tokenTypes`, case-insensitive). */
     tokenTypes?: readonly string[] | undefined;
 }
+/**
+ * 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 declare function tokenRequestInit(client: OAuthClientRecord, params: Record<string, string | undefined>): {
+    headers: Record<string, string>;
+    body: URLSearchParams;
+};
+/** The form encoding of a Basic client credential part (RFC 6749 §2.3.1). */
+export declare const formEncode: (s: string) => string;
+/** The `Authorization` value of `client_secret_basic` (both parts form-encoded first). */
+export declare const basicClientAuth: (clientId: string, clientSecret: string) => string;
+/**
+ * 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 declare function parseTokenRefusal(status: number, body: unknown): string | 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).

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.d.ts

@@ -151,8 +151,9 @@ interface PipelineDeps {
     /** The org's switches of single extension tools: a turned-off one is not called (spec A §7). */
     readonly switches: Pick<OrgToolSwitches, "isToolOff">;
     /**
-     * Ids of an extension's `inline` ui contributions (read live, no alias): a plugin tool's
-     * `ToolResult.card` must name one of them, otherwise it is dropped with a warning.
+     * Ids of an extension's `conversation.tool-result.card` contributions of any kind (view, embed
+     * or component; read live, no alias): a plugin tool's `ToolResult.card` must name one of them,
+     * otherwise it is dropped with a warning.
      */
     inlineViews(plugin: string): ReadonlySet<string>;
     /**

package/dist/ui/arrangement.d.ts

@@ -1,74 +1,65 @@
 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>;
+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.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>>>;
+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.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>>>;
+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 entry that applies to a slot: the org's if it arranged the slot, else the platform's. */
+/**
+ * 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: UiArrangementEntry;
+    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: UiArrangementEntry): UiContributionItem[];
+export declare function orderItems(items: UiContributionItem[], entry: UiListEntry): UiContributionItem[];
 /** {@link orderItems} without the hidden keys. */
-export declare function arrange(items: UiContributionItem[], entry: UiArrangementEntry): UiContributionItem[];
+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) => UiArrangementEntry): UiContributionItem[];
+export declare function arrangeBySlot(items: UiContributionItem[], entryOf: (slot: UiSlotId) => UiListEntry): UiContributionItem[];

package/dist/ui/arrangement.js

@@ -1,22 +1,66 @@
-import { UI_ARRANGEABLE_SLOTS, UI_CONTRIBUTION_KEY_RE, uiSlot, } from "@capybara-hq/plugin-sdk";
+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): 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.
+ * 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);
+const Key = z.string().regex(UI_CONTRIBUTION_KEY_RE, "must be a contribution key <plugin>/<id>");
 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);
+/**
+ * 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 = z.partialRecord(z.enum(ORG_ARRANGEABLE), UiArrangementEntrySchema.nullable());
+export const OrgUiArrangementPatchSchema = arrangementShape(ORG_ARRANGEABLE, true);
 /** A deployment patch: like {@link OrgUiArrangementPatchSchema} over every arrangeable slot. */
-export const UiArrangementPatchSchema = z.partialRecord(z.enum(UI_ARRANGEABLE_SLOTS), UiArrangementEntrySchema.nullable());
+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 };
@@ -29,17 +73,46 @@ export function mergeArrangement(current, patch) {
     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. */
+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: o, source: "org" };
+        return { entry: asList(o), source: "org" };
     const p = platform[slot];
     if (p !== undefined)
-        return { entry: p, source: "platform" };
+        return { entry: asList(p), source: "platform" };
     return { entry: NONE, source: "none" };
 }
-const keyOf = (i) => `${i.plugin}/${i.id}`;
+/**
+ * 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

package/dist/ui/registry.d.ts

@@ -45,19 +45,29 @@ export declare const uiFrame: (m: UiBusMessage) => string;
 /**
  * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
  * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
- * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ * The id must be in `permissions.ui.views` or `permissions.ui.components` (a component's server
+ * view, client extensions spec §5.2); `defineExtension` already cross-checked them with the
+ * manifest `ui`.
  */
 export declare class PluginUiRegistration {
     private readonly manifest;
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     private readonly deny;
     readonly views: Map<string, UiRender>;
     readonly actions: Map<string, UiActionHandler>;
     private readonly declaredViews;
     private readonly contributions;
+    /** The ids of the manifest's `component` contributions: their permission is `ui.components`. */
+    private readonly components;
     private sealed;
     constructor(manifest: ExtensionManifest, 
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     deny: (item: string) => never);
     /** setup 结束后调用：此后 view / action 抛错。 */
     seal(): void;

package/dist/ui/registry.js

@@ -31,7 +31,9 @@ export const uiFrame = (m) => `event: ui\ndata: ${JSON.stringify({ plugin: m.plu
 /**
  * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
  * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
- * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ * The id must be in `permissions.ui.views` or `permissions.ui.components` (a component's server
+ * view, client extensions spec §5.2); `defineExtension` already cross-checked them with the
+ * manifest `ui`.
  */
 export class PluginUiRegistration {
     manifest;
@@ -40,14 +42,21 @@ export class PluginUiRegistration {
     actions = new Map();
     declaredViews;
     contributions;
+    /** The ids of the manifest's `component` contributions: their permission is `ui.components`. */
+    components;
     sealed = false;
     constructor(manifest, 
-    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    /**
+     * Out of scope (the id is in neither `permissions.ui.views` nor `permissions.ui.components`):
+     * throws ExtensionPermissionError and writes an audit entry.
+     */
     deny) {
         this.manifest = manifest;
         this.deny = deny;
-        this.declaredViews = new Set(manifest.permissions?.ui?.views ?? []);
+        const ui = manifest.permissions?.ui;
+        this.declaredViews = new Set([...(ui?.views ?? []), ...(ui?.components ?? [])]);
         this.contributions = new Set((manifest.ui ?? []).map((c) => c.id));
+        this.components = new Set((manifest.ui ?? []).filter((c) => c.kind === "component").map((c) => c.id));
     }
     /** setup 结束后调用：此后 view / action 抛错。 */
     seal() {
@@ -99,7 +108,9 @@ export class PluginUiRegistration {
             throw new Error(`plugin ${name}: ui.${what} is only allowed during setup; setup has completed`);
         }
         if (typeof id !== "string" || !this.declaredViews.has(id)) {
-            this.deny(`permissions.ui.views ${String(id)}`);
+            // name the list the id belongs in: a component's server view is declared under components
+            const list = typeof id === "string" && this.components.has(id) ? "components" : "views";
+            this.deny(`permissions.ui.${list} ${String(id)}`);
         }
         if (typeof fn !== "function") {
             throw new Error(`plugin ${name}: ui.${what} "${id}" handler must be a function`);

package/dist/ui/ui.schemas.d.ts

@@ -9,6 +9,8 @@ export declare const ContributionParams: z.ZodObject<{
 export declare const ContributionsQuery: z.ZodObject<{
     slot: z.ZodOptional<z.ZodEnum<{
         "agent.detail.section": "agent.detail.section";
+        "conversation.composer.frame": "conversation.composer.frame";
+        "conversation.empty": "conversation.empty";
         "conversation.panel": "conversation.panel";
         "conversation.properties.section": "conversation.properties.section";
         "conversation.tool-result.card": "conversation.tool-result.card";
@@ -16,6 +18,8 @@ export declare const ContributionsQuery: z.ZodObject<{
         "org.page": "org.page";
         "org.settings.section": "org.settings.section";
         "platform.page": "platform.page";
+        "shell.brand": "shell.brand";
+        "shell.overlay": "shell.overlay";
     }>>;
 }, z.core.$strip>;
 export declare const ViewQuery: z.ZodObject<{