@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/background/wake-rules.d.ts

@@ -0,0 +1,66 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * The wake rules of an idle conversation (spec 2026-11-05-background-bash-design §3, generalized
+ * by agent map spec §5.3 to a second event kind): a finished background task or a sub-agent's
+ * delivery starts a run. Read by `RunQueue.ensureRun` in its transaction: every path that may start
+ * a run (a finish, a delivery, the end of a run, the delayed wake job, a page opening) applies the
+ * same rules. `BackgroundWake` is what calls `ensureRun` when a task finishes or a delivery lands.
+ */
+/** No two wakes of one conversation start within this window. */
+export declare const WAKE_WINDOW_MS = 60000;
+/** The delayed job that wakes a conversation at the end of its window (`cap-kernel-maintenance`). */
+export declare const BG_WAKE_JOB = "bg-wake";
+/**
+ * Its job id: one job per conversation and window end (no `:`). `retry` > 0 is a job that fired
+ * before the window ended on the database's clock and scheduled itself again: a distinct id, since
+ * BullMQ ignores an add under the id of the job still running.
+ */
+export declare const bgWakeJobId: (conversationId: string, windowEnd: number, retry?: number) => string;
+export interface BgWakeJobData {
+    conversationId: string;
+    /** How many times this window's wake fired early (absent: none). */
+    retry?: number;
+}
+/**
+ * What a conversation's unconsumed wake events decide:
+ * - `wake`: start a run whose boundary is the event at `seq`, as `triggerAccountId`;
+ * - `later`: a wake started less than {@link WAKE_WINDOW_MS} ago; the window ends at `windowEnd`
+ *   (epoch ms, the database's clock), `delayMs` from now;
+ * - null: nothing wakes the conversation.
+ */
+export type WakeDecision = {
+    kind: "wake";
+    seq: number;
+    triggerAccountId: string;
+} | {
+    kind: "later";
+    windowEnd: number;
+    delayMs: number;
+} | null;
+/**
+ * The wake decision for a conversation that is idle and has no unconsumed message (the caller
+ * checked these under the conversation's row lock): a chat conversation (`rootId` = its own id) or
+ * a sub-agent's (`rootId` = the root of its tree). An event wakes it when:
+ * - it is after `consumed` and is either
+ *   - a `background_task_finished` of a task of this conversation (the join on `conversation_id`
+ *     reads the task's trigger account) that is not `reported` (a tool call already told the model)
+ *     and has no `stoppedBy` (`"person"`: that person is looking at the conversation;
+ *     `"deletion"`: the conversation is being deleted), or
+ *   - a `subagent_delivery` (its own `triggerAccountId`: the trigger account of the child run that
+ *     delivered it, agent map spec §7), except the finish of a child that was stopped
+ *     (`status: "aborted"`: a person's stop of it or of a sub-agent above it, a tree stop, the
+ *     deletion of the root), for the same reason as a person's task stop; a tree stop thus never
+ *     wakes the stopped ancestors through their descendants' finishes, which land after them;
+ * - the wake setting is on (the org's override, else `deploymentOn`);
+ * - the root's queue is not paused and the root is not deleted (a paused root holds the wakes of
+ *   the whole tree, agent map spec §5.3);
+ * - the event's trigger account can still send to the root (`canSend`, which the caller binds to
+ *   the root);
+ * - no other wake of this conversation started in the last {@link WAKE_WINDOW_MS} (else `later`).
+ * The boundary is the newest event whose trigger account can send.
+ */
+export declare function wakeDecisionIn(t: KernelSchemaDb, conv: {
+    id: string;
+    orgId: string;
+    rootId: string;
+}, consumed: number, deploymentOn: boolean, canSend: (accountId: string) => Promise<boolean>): Promise<WakeDecision>;

package/dist/background/wake-rules.js

@@ -0,0 +1,113 @@
+import { sql } from "kysely";
+import { effectiveWakeOnBackgroundTask, readOrgSettings } from "../orgs/settings.service.js";
+/**
+ * The wake rules of an idle conversation (spec 2026-11-05-background-bash-design §3, generalized
+ * by agent map spec §5.3 to a second event kind): a finished background task or a sub-agent's
+ * delivery starts a run. Read by `RunQueue.ensureRun` in its transaction: every path that may start
+ * a run (a finish, a delivery, the end of a run, the delayed wake job, a page opening) applies the
+ * same rules. `BackgroundWake` is what calls `ensureRun` when a task finishes or a delivery lands.
+ */
+/** No two wakes of one conversation start within this window. */
+export const WAKE_WINDOW_MS = 60_000;
+/** The delayed job that wakes a conversation at the end of its window (`cap-kernel-maintenance`). */
+export const BG_WAKE_JOB = "bg-wake";
+/**
+ * Its job id: one job per conversation and window end (no `:`). `retry` > 0 is a job that fired
+ * before the window ended on the database's clock and scheduled itself again: a distinct id, since
+ * BullMQ ignores an add under the id of the job still running.
+ */
+export const bgWakeJobId = (conversationId, windowEnd, retry = 0) => `bg-wake-${conversationId}-${windowEnd}${retry > 0 ? `-r${retry}` : ""}`;
+/** How many unconsumed events are tried for a trigger account that can still send. */
+const CANDIDATES = 20;
+/** The event types whose run is a wake run (its boundary, `runs.trigger_seq`, is one of them). */
+const WAKE_EVENT_TYPES = ["background_task_finished", "subagent_delivery"];
+/**
+ * The wake decision for a conversation that is idle and has no unconsumed message (the caller
+ * checked these under the conversation's row lock): a chat conversation (`rootId` = its own id) or
+ * a sub-agent's (`rootId` = the root of its tree). An event wakes it when:
+ * - it is after `consumed` and is either
+ *   - a `background_task_finished` of a task of this conversation (the join on `conversation_id`
+ *     reads the task's trigger account) that is not `reported` (a tool call already told the model)
+ *     and has no `stoppedBy` (`"person"`: that person is looking at the conversation;
+ *     `"deletion"`: the conversation is being deleted), or
+ *   - a `subagent_delivery` (its own `triggerAccountId`: the trigger account of the child run that
+ *     delivered it, agent map spec §7), except the finish of a child that was stopped
+ *     (`status: "aborted"`: a person's stop of it or of a sub-agent above it, a tree stop, the
+ *     deletion of the root), for the same reason as a person's task stop; a tree stop thus never
+ *     wakes the stopped ancestors through their descendants' finishes, which land after them;
+ * - the wake setting is on (the org's override, else `deploymentOn`);
+ * - the root's queue is not paused and the root is not deleted (a paused root holds the wakes of
+ *   the whole tree, agent map spec §5.3);
+ * - the event's trigger account can still send to the root (`canSend`, which the caller binds to
+ *   the root);
+ * - no other wake of this conversation started in the last {@link WAKE_WINDOW_MS} (else `later`).
+ * The boundary is the newest event whose trigger account can send.
+ */
+export async function wakeDecisionIn(t, conv, consumed, deploymentOn, canSend) {
+    const finishes = await t
+        .selectFrom("conversation_events as e")
+        .innerJoin("background_tasks as b", (j) => j
+        .on(sql `b.id = e.payload ->> 'taskId'`)
+        .onRef("b.conversation_id", "=", "e.conversation_id"))
+        .select(["e.seq", "b.trigger_account_id as account"])
+        .where("e.conversation_id", "=", conv.id)
+        .where("e.type", "=", "background_task_finished")
+        .where("e.seq", ">", String(consumed))
+        .where(sql `(e.payload ->> 'reported')::boolean = false`)
+        .where(sql `e.payload ->> 'stoppedBy' IS NULL`)
+        .orderBy("e.seq", "desc")
+        .limit(CANDIDATES)
+        .execute();
+    const deliveries = await t
+        .selectFrom("conversation_events as e")
+        .select(["e.seq", sql `e.payload ->> 'triggerAccountId'`.as("account")])
+        .where("e.conversation_id", "=", conv.id)
+        .where("e.type", "=", "subagent_delivery")
+        .where("e.seq", ">", String(consumed))
+        .where(sql `e.payload ->> 'status' IS DISTINCT FROM 'aborted'`)
+        .orderBy("e.seq", "desc")
+        .limit(CANDIDATES)
+        .execute();
+    const candidates = [...finishes, ...deliveries]
+        .sort((a, b) => Number(b.seq) - Number(a.seq))
+        .slice(0, CANDIDATES);
+    if (candidates.length === 0)
+        return null;
+    const org = (await readOrgSettings(t, conv.orgId)).wakeOnBackgroundTask;
+    if (!effectiveWakeOnBackgroundTask(deploymentOn, org))
+        return null;
+    const root = await t
+        .selectFrom("conversations")
+        .select(["queue_paused", "deleted_at"])
+        .where("id", "=", conv.rootId)
+        .executeTakeFirst();
+    if (!root || root.queue_paused || root.deleted_at !== null)
+        return null;
+    let boundary;
+    for (const c of candidates) {
+        if (await canSend(c.account)) {
+            boundary = { seq: Number(c.seq), triggerAccountId: c.account };
+            break;
+        }
+    }
+    if (boundary === undefined)
+        return null;
+    // the window starts when the last wake run was created (PG, so every replica reads the same)
+    const last = await t
+        .selectFrom("runs as r")
+        .innerJoin("conversation_events as w", (j) => j.onRef("w.conversation_id", "=", "r.conversation_id").onRef("w.seq", "=", "r.trigger_seq"))
+        .select([
+        sql `floor(extract(epoch from max(r.created_at)) * 1000)::bigint`.as("started"),
+        sql `floor(extract(epoch from now()) * 1000)::bigint`.as("now"),
+    ])
+        .where("r.conversation_id", "=", conv.id)
+        .where("w.type", "in", WAKE_EVENT_TYPES)
+        .executeTakeFirst();
+    if (last?.started != null) {
+        const windowEnd = Number(last.started) + WAKE_WINDOW_MS;
+        const now = Number(last.now);
+        if (windowEnd > now)
+            return { kind: "later", windowEnd, delayMs: windowEnd - now };
+    }
+    return { kind: "wake", ...boundary };
+}

package/dist/background/wake.d.ts

@@ -0,0 +1,30 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type OnApplicationShutdown } from "@nestjs/common";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { RunQueue } from "../runtime/run-queue.js";
+/**
+ * Wakes an idle conversation when one of its background tasks finished (spec
+ * 2026-11-05-background-bash-design §3) or a sub-agent delivered to it (agent map spec §5.3).
+ * {@link BackgroundTaskFinisher} announces the committed finish (`background_task.finished`) and
+ * `SubagentDeliveries` the committed delivery (`subagent.delivered`), both in-process domain
+ * events emitted after the commit; {@link onFinished} asks the run queue for a run. The wake rules
+ * themselves (own task, not reported, the wake setting, the root's queue not paused, the trigger
+ * account can still send to the root, the 60 s window and its delayed `bg-wake` job) are applied
+ * by `RunQueue.ensureRun` in its transaction (`wakeDecisionIn`, ./wake-rules.ts), so a run's end,
+ * the delayed job and a page opening apply the same rules; a lost event is re-derived by the next
+ * of them. Provided by `RuntimeModule`.
+ */
+export declare class BackgroundWake implements OnApplicationShutdown {
+    private readonly runs;
+    private readonly log;
+    /** Drops the subscriptions (the events may outlive this instance). */
+    private readonly unsubscribe;
+    constructor(runs: Pick<RunQueue, "ensureRun">, events: KernelEvents, log: Pick<Logger, "warn">);
+    /**
+     * A task of `conversationId` finished, or a sub-agent delivered to it (after the commit): starts
+     * a wake run when the rules allow it, or schedules one at the end of the wake window. A run in
+     * progress absorbs the event at its next step instead, or its end starts the wake. Never throws.
+     */
+    onFinished(conversationId: string): Promise<void>;
+    onApplicationShutdown(): void;
+}

package/dist/background/wake.js

@@ -0,0 +1,63 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { RunQueue } from "../runtime/run-queue.js";
+/**
+ * Wakes an idle conversation when one of its background tasks finished (spec
+ * 2026-11-05-background-bash-design §3) or a sub-agent delivered to it (agent map spec §5.3).
+ * {@link BackgroundTaskFinisher} announces the committed finish (`background_task.finished`) and
+ * `SubagentDeliveries` the committed delivery (`subagent.delivered`), both in-process domain
+ * events emitted after the commit; {@link onFinished} asks the run queue for a run. The wake rules
+ * themselves (own task, not reported, the wake setting, the root's queue not paused, the trigger
+ * account can still send to the root, the 60 s window and its delayed `bg-wake` job) are applied
+ * by `RunQueue.ensureRun` in its transaction (`wakeDecisionIn`, ./wake-rules.ts), so a run's end,
+ * the delayed job and a page opening apply the same rules; a lost event is re-derived by the next
+ * of them. Provided by `RuntimeModule`.
+ */
+let BackgroundWake = class BackgroundWake {
+    runs;
+    log;
+    /** Drops the subscriptions (the events may outlive this instance). */
+    unsubscribe;
+    constructor(runs, events, log) {
+        this.runs = runs;
+        this.log = log;
+        this.unsubscribe = [
+            events.on("background_task.finished", ({ conversationId }) => this.onFinished(conversationId)),
+            events.on("subagent.delivered", ({ conversationId }) => this.onFinished(conversationId)),
+        ];
+    }
+    /**
+     * A task of `conversationId` finished, or a sub-agent delivered to it (after the commit): starts
+     * a wake run when the rules allow it, or schedules one at the end of the wake window. A run in
+     * progress absorbs the event at its next step instead, or its end starts the wake. Never throws.
+     */
+    async onFinished(conversationId) {
+        try {
+            await this.runs.ensureRun(conversationId);
+        }
+        catch (err) {
+            this.log.warn("background wake failed", { conversationId, err });
+        }
+    }
+    onApplicationShutdown() {
+        for (const off of this.unsubscribe)
+            off();
+    }
+};
+BackgroundWake = __decorate([
+    Injectable(),
+    __param(0, Inject(RunQueue)),
+    __param(1, Inject(KernelEvents)),
+    __param(2, Inject(KERNEL_LOGGER))
+], BackgroundWake);
+export { BackgroundWake };

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

@@ -1,10 +1,11 @@
 import type { FastifyReply } from "fastify";
 import { z } from "zod";
-import type { AdminExtensionView } from "../extensions/permission-view.js";
 import { type Principal } from "../identity/principal.js";
 import { type CatalogItemDetail, type CatalogItemView, CatalogService, type PermissionsMismatch } from "./catalog.service.js";
+import { CatalogScopeService, type ScopePreview } from "./catalog-scope.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
 import { type PluginConfirmResult, PluginImport, type PluginReview } from "./plugin-import.js";
+import { PlatformPluginUpdater, type PlatformUpdatePreview, type PlatformUpdateResult } from "./plugin-upgrade.js";
 declare const NpmBody: z.ZodObject<{
     package: z.ZodString;
     version: z.ZodOptional<z.ZodString>;
@@ -14,21 +15,42 @@ declare const GitBody: z.ZodObject<{
     ref: z.ZodOptional<z.ZodString>;
     path: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-declare const PolicyBody: z.ZodObject<{
-    policy: z.ZodEnum<{
-        allow: "allow";
-        disabled: "disabled";
-        needs_approval: "needs_approval";
-    }>;
-}, z.core.$strip>;
-declare const InstallBody: z.ZodObject<{
-    version: z.ZodString;
-}, z.core.$strip>;
 declare const ConfirmBody: z.ZodObject<{
     reviewHash: z.ZodString;
-    deployExtension: z.ZodBoolean;
+    scope: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     pinnedSuggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
+}, z.core.$strict>;
+/** `{ scope, orgs? }` (a scope change) or `{ disabled: true }` (a disable), not both. */
+declare const ScopePreviewBody: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disabled: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+declare const ScopeBody: z.ZodObject<{
+    scope: z.ZodEnum<{
+        all: "all";
+        named: "named";
+        optional: "optional";
+    }>;
+    orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scopeHash: z.ZodString;
+}, z.core.$strict>;
+declare const DisabledBody: z.ZodObject<{
+    disabled: z.ZodBoolean;
+    scopeHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const ShownBody: z.ZodObject<{
+    shownToOthers: z.ZodBoolean;
+}, z.core.$strict>;
 declare const ListQuery: z.ZodObject<{
     includeDeleted: z.ZodOptional<z.ZodEnum<{
         false: "false";
@@ -36,18 +58,38 @@ declare const ListQuery: z.ZodObject<{
     }>>;
     limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    pending: z.ZodOptional<z.ZodEnum<{
+        false: "false";
+        true: "true";
+    }>>;
 }, z.core.$strip>;
+declare const ConfirmPermissionsBody: z.ZodObject<{
+    permissionsHash: z.ZodString;
+}, z.core.$strict>;
+/** The reason shown to the owner org in its `upload_rejected` notice (optional). */
+declare const RejectBody: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const UpdatePreviewBody: z.ZodObject<{
+    version: z.ZodString;
+}, z.core.$strict>;
+declare const UpdateBody: z.ZodObject<{
+    version: z.ZodString;
+    diffHash: z.ZodString;
+}, z.core.$strict>;
 /**
- * The enterprise catalog (`/api/v1/admin/catalog/*`, enterprise admins): plugin import (upload / npm
- * prepare, then confirm), the item list and detail, policy, delete, and installing an item's
- * extension on the deployment. Writes re-check the enterprise admin inside the service's lock and are
+ * The platform catalog (`/api/v1/admin/catalog/*`, super admins): plugin import (upload / npm
+ * prepare, then confirm, which installs the plugin's extension), the item list and detail, scope and
+ * disable (previewed, then confirmed with `scopeHash`), delete. Writes re-check the super admin inside the service's lock and are
  * audited.
  */
 export declare class AdminCatalogController {
     private readonly catalog;
     private readonly pluginImport;
     private readonly orgCatalog;
-    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService);
+    private readonly scope;
+    private readonly updater;
+    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService, scope: CatalogScopeService, updater: PlatformPluginUpdater);
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
      * `application/octet-stream`, at most `packages.maxBytes`): reads and checks the whole plugin
@@ -97,11 +139,13 @@ export declare class AdminCatalogController {
         permissionsMismatch?: PermissionsMismatch;
     }>;
     /**
-     * Confirms a staged import: approves the plugin's extension when this import installs it (writes
-     * its snapshot) and creates the item or adds the version; with `deployExtension` it installs and
-     * enables the plugin's own extension after the commit and returns `{ item, deploy }`, where
-     * `deploy` says enabled / failed (+ code); a failed deploy does not make the committed import fail
-     * (retry from the extension admin by sha256). A foreseeable failure (a downgrade to a version with
+     * Confirms a staged import: approves the plugin's extension when this import installs or upgrades
+     * it (writes its snapshot), creates the item (with `scope`, default `optional`; `orgs` only with
+     * `named`, each an existing org, else 400 `validation_failed`) or adds the version, installs and
+     * enables the plugin's own extension after the commit and enqueues the item's scope sync; returns
+     * `{ item, deploy }`, where `deploy` says enabled / failed (+ code), null without an extension to
+     * deploy; a failed deploy does not make the committed import fail (retry from the extension admin
+     * by sha256). An unknown field (the removed `deployExtension`) -> 400 `validation_failed`. A foreseeable failure (a downgrade to a version with
      * unrun migrations) is a 409 `extension.downgrade_unsupported` before anything is written.
      * Staging missing or expired -> 404 `plugin.staging_not_found`; `reviewHash` differs or the
      * extension on the deployment changed -> 409 `plugin.review_stale`. `pinnedSuggestions` (skill
@@ -129,15 +173,70 @@ export declare class AdminCatalogController {
      * `sendCatalogIcon`). No icon -> 404 `catalog.icon_not_found`.
      */
     icon(id: string, reply: FastifyReply): Promise<void>;
-    /** 改策略（allow / needs_approval / disabled）。 */
-    setPolicy(principal: Principal, id: string, body: z.infer<typeof PolicyBody>): Promise<CatalogItemView>;
-    /** 删除条目（软删除，已安装的组件不受影响）。 */
-    remove(principal: Principal, id: string): Promise<void>;
     /**
-     * Installs the extension of a version of an item on the deployment (a new install starts disabled;
-     * unapproved permissions still need approval). A version without an extension -> 409
-     * `catalog.no_extension`.
+     * What a scope change (`{ scope, orgs? }`, `orgs` only with `named`) or a disable
+     * (`{ disabled: true }`) would take away: `{ affected: [{ orgId, orgName, agents,
+     * connectorsKept }], needsConfig, scopeHash }` (spec §5 rule 8; nothing written; the connectors
+     * stay as the orgs' own). A builtin item -> 409 `plugin.builtin`; unknown
+     * orgs -> 400 `validation_failed`.
+     */
+    previewScope(id: string, body: z.infer<typeof ScopePreviewBody>): Promise<ScopePreview>;
+    /**
+     * Changes the scope, confirmed with the preview's `scopeHash` (recomputed under the item row lock;
+     * a difference -> 409 `plugin.scope_stale`); bumps the scope version, audits
+     * `catalog.scope_changed` and enqueues the scope sync. Builtin -> 409 `plugin.builtin`.
+     */
+    setScope(principal: Principal, id: string, body: z.infer<typeof ScopeBody>): Promise<CatalogItemView>;
+    /**
+     * Disables the plugin on the whole deployment (`scopeHash` of the `{ disabled: true }` preview
+     * required; the scope sync then uninstalls it everywhere, its scope and the org switches are kept)
+     * or enables it again (no hash; the sync reinstalls where it is wanted). Builtin -> 409
+     * `plugin.builtin`; a stale hash -> 409 `plugin.scope_stale`.
+     */
+    setDisabled(principal: Principal, id: string, body: z.infer<typeof DisabledBody>): Promise<CatalogItemView>;
+    /**
+     * Confirms the item's extension permissions (the admin's 待确认; body `{ permissionsHash }` from
+     * the item view): approves the current permission set (snapshot source `web`) and installs and
+     * enables an extension that was never deployed. A changed set -> 409 `extension.approval_stale`;
+     * nothing to confirm -> 409 `extension.not_pending`. Returns the item. An org's upload
+     * (`owner.kind` org, ruling P3-10): the digest of its pending version's package; a first version
+     * is installed, approved, enabled and synced, a new version applied by the platform update
+     * (the item removed meanwhile -> 409 `catalog.item_removed`, P3-21).
      */
-    installToDeployment(principal: Principal, id: string, body: z.infer<typeof InstallBody>): Promise<AdminExtensionView>;
+    confirmPermissions(principal: Principal, id: string, body: z.infer<typeof ConfirmPermissionsBody>): Promise<CatalogItemView>;
+    /**
+     * Rejects an org upload's pending version (ruling P3-10; body `{ reason? }`, told to the owner
+     * org in `upload_rejected`): a first version is removed (its name free again), a new version's
+     * pending state cleared. Nothing pending, or a platform item (pre-flight F11) -> 409
+     * `extension.not_pending`. 204.
+     */
+    reject(principal: Principal, id: string, body: z.infer<typeof RejectBody>): Promise<void>;
+    /**
+     * Whether orgs outside a `named` item's list see it as requestable (spec §5.1 rule 1). Hiding it
+     * keeps pending requests as they are; new requests from unlisted orgs are then 404. Never makes
+     * anything usable, so no preview and no scope sync. Audits `catalog.shown_changed`.
+     */
+    setShown(principal: Principal, id: string, body: z.infer<typeof ShownBody>): Promise<CatalogItemView>;
+    /**
+     * What updating the platform plugin to `version` would do (spec §7.1, `PlatformPluginUpdater`):
+     * `{ itemId, name, from, to, components: [{ kind, id, name, change: added | removed | upgrade |
+     * downgrade | same, from, to, updatedOnOwn, ownScope, pinnedOrgs, kept? }], extension,
+     * connectorOrgs: [{ orgId, connectors, needsConfig }], diffHash }`. Nothing written. The same
+     * version, a target the deployment's extension or a dependent plugin cannot take -> 409
+     * `plugin.upgrade_target_invalid`; an added skill named like one in use where the plugin is on
+     * -> 409 `plugin.skill_conflict`; disabled -> 403 `catalog.item_disabled`.
+     */
+    previewUpdate(id: string, body: z.infer<typeof UpdatePreviewBody>): Promise<PlatformUpdatePreview>;
+    /**
+     * Updates the platform plugin, confirmed with the preview's `diffHash` (recomputed under the item
+     * lock; a difference -> 409 `plugin.upgrade_stale`; another update running -> 409
+     * `plugin.install_in_progress`). A failure undoes everything -> 502 `plugin.upgrade_failed`.
+     * Audits `plugin.platform_updated`. A version an org upload waits with (or an item whose first
+     * version waits) -> 409 `catalog.item_pending`: confirm it in 待确认 (pre-flight F8); the
+     * preview answers the same.
+     */
+    update(principal: Principal, id: string, body: z.infer<typeof UpdateBody>): Promise<PlatformUpdateResult>;
+    /** 删除条目（软删除，已安装的组件不受影响）。 */
+    remove(principal: Principal, id: string): Promise<void>;
 }
 export {};