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

package/dist/background/tasks.service.js

@@ -11,13 +11,17 @@ import { isSandboxGoneError } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ConversationAccess } from "../conversations/access.js";
 import { EventLog } from "../conversations/event-log.js";
+import { conversationTree } from "../conversations/tree.js";
+import { ConversationEnvironments } from "../environments/conversation-environments.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { UUID_RE } from "../ui/registry.js";
 import { finishedEventKey } from "./finish.js";
 import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
+import { actingAs } from "./session.js";
 import { BackgroundTaskStopper } from "./stop.js";
 import { BackgroundTaskStore } from "./store.js";
 /** The most bytes of output one read returns. */
@@ -29,7 +33,7 @@ const taskNotFound = () => new ApiError("background_task.not_found", "Background
 /**
  * The HTTP side of background tasks (spec 2026-11-05-background-bash-design §5): the tasks of a
  * conversation and of its sub-agents, stopping one, reading its output. A task is reachable
- * through the conversation that owns it or through that conversation's parent, and only by a
+ * through the conversation that owns it or through any conversation above it, and only by a
  * person who may see the conversation (`ConversationAccess`, the rule of `GET :id`, which is also
  * what `POST :id/abort` checks: the owner).
  */
@@ -40,28 +44,27 @@ let BackgroundTasks = class BackgroundTasks {
     sandbox;
     eventLog;
     db;
-    constructor(access, store, stopper, sandbox, eventLog, db) {
+    environments;
+    constructor(access, store, stopper, sandbox, eventLog, db, environments) {
         this.access = access;
         this.store = store;
         this.stopper = stopper;
         this.sandbox = sandbox;
         this.eventLog = eventLog;
         this.db = db;
+        this.environments = environments;
     }
-    /** The conversation and its sub-agents' conversations; `conversation.not_found` when not visible. */
+    /**
+     * The conversation and every sub-agent conversation below it (grandchildren too: their tasks run
+     * in the root's sandbox, agent map spec §6); `conversation.not_found` when not visible.
+     */
     async scope(orgId, conversationId, accountId) {
         if (!UUID_RE.test(conversationId) ||
             !(await this.access.isAccessible(orgId, conversationId, accountId))) {
             throw conversationNotFound();
         }
-        const children = await this.db
-            .selectFrom("conversations")
-            .select("id")
-            .where("org_id", "=", orgId)
-            .where("parent_conversation_id", "=", conversationId)
-            .where("kind", "=", "subagent")
-            .execute();
-        return [conversationId, ...children.map((c) => c.id)];
+        // the conversation is the org's (isAccessible), and so is every sub-agent conversation below it
+        return (await conversationTree(this.db.db, conversationId)).map((c) => c.id);
     }
     view(task, conversationId) {
         return {
@@ -111,18 +114,39 @@ let BackgroundTasks = class BackgroundTasks {
         return this.view(after, conversationId);
     }
     /**
-     * The end of the task's output, at most `tail` bytes. Read live when the task's sandbox instance
-     * runs (never resuming a suspended sandbox); a finished task whose sandbox does not run answers
+     * Whether the task's environment may still be used by its conversation's owner (the access
+     * re-check every sandbox tool call makes); when it may not, the live read is skipped.
+     */
+    async environmentUsable(orgId, taskConversationId) {
+        try {
+            await this.environments.forTool(orgId, await rootConversationOf(this.db.db, taskConversationId));
+            return true;
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * The end of the task's output, at most `tail` bytes. Read live when the task's environment
+     * instance runs (never resuming a suspended one); a finished task whose sandbox does not run answers
      * with the last lines its finished event kept. Anything else is
      * `background_task.output_unavailable` (409).
      */
     async output(orgId, conversationId, accountId, taskId, tail) {
         const task = await this.owned(orgId, conversationId, accountId, taskId);
-        if (task.sid !== null && task.sandboxCreatedAt !== null && this.sandbox.available) {
+        if (task.sid !== null &&
+            task.sandboxCreatedAt !== null &&
+            task.environmentId !== null &&
+            this.sandbox.available &&
+            (await this.environmentUsable(orgId, task.conversationId))) {
             const createdAt = task.sandboxCreatedAt;
+            // the person reading it acts in the task's conversation
+            const actor = { accountId, conversationId: task.conversationId };
             try {
-                const r = await this.sandbox.ifRunning(task.sandboxConversationId, { createdAt }, async (p, h, signal) => {
-                    const res = await p.exec(h, {
+                const r = await this.sandbox.ifRunning(task.environmentId, { createdAt }, async (p, h, signal) => {
+                    const res = await actingAs(p, actor).exec(h, {
                         command: tailScript(task.id, tail),
                         cwd: "/workspace",
                         timeoutMs: OUTPUT_READ_TIMEOUT_MS,
@@ -155,7 +179,8 @@ BackgroundTasks = __decorate([
     __param(2, Inject(BackgroundTaskStopper)),
     __param(3, Inject(SandboxService)),
     __param(4, Inject(EventLog)),
-    __param(5, Inject(KernelDb))
+    __param(5, Inject(KernelDb)),
+    __param(6, Inject(ConversationEnvironments))
 ], BackgroundTasks);
 export { BackgroundTasks };
 /** Prints `size <bytes>` and `out <base64 of the last `tail` bytes>`. Relative to `/workspace`. */

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

@@ -1,9 +1,10 @@
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 /**
- * The wake rules of a finished background task (spec 2026-11-05-background-bash-design §3), read
- * by `RunQueue.ensureRun` in its transaction: every path that may start a run (a finish, 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.
+ * 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;
@@ -21,8 +22,8 @@ export interface BgWakeJobData {
     retry?: number;
 }
 /**
- * What a conversation's unconsumed finishes decide:
- * - `wake`: start a run whose boundary is the finish at `seq`, as `triggerAccountId`;
+ * 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.
@@ -37,21 +38,29 @@ export type WakeDecision = {
     delayMs: number;
 } | null;
 /**
- * The wake decision for a chat conversation that is idle, whose queue is not paused and has no
- * unconsumed message (the caller checked these under the conversation's row lock). A finish
- * wakes it when:
- * - it is after `consumed`, 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);
- * - it belongs to a task of this conversation (the join on `conversation_id` reads the task's
- *   trigger account). A sub-agent's task is excluded by the conversation's kind, not here: its
- *   finish is in the child's log, and `ensureRun` never wakes a non-chat conversation;
+ * 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 task's trigger account can still send to the conversation (`canSend`);
- * - no other wake started in the last {@link WAKE_WINDOW_MS} (else `later`).
- * The boundary is the newest finish whose trigger account can send.
+ * - 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

@@ -1,10 +1,11 @@
 import { sql } from "kysely";
 import { effectiveWakeOnBackgroundTask, readOrgSettings } from "../orgs/settings.service.js";
 /**
- * The wake rules of a finished background task (spec 2026-11-05-background-bash-design §3), read
- * by `RunQueue.ensureRun` in its transaction: every path that may start a run (a finish, 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.
+ * 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;
@@ -16,30 +17,39 @@ export const BG_WAKE_JOB = "bg-wake";
  * 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 finishes are tried for a trigger account that can still send. */
+/** 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 chat conversation that is idle, whose queue is not paused and has no
- * unconsumed message (the caller checked these under the conversation's row lock). A finish
- * wakes it when:
- * - it is after `consumed`, 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);
- * - it belongs to a task of this conversation (the join on `conversation_id` reads the task's
- *   trigger account). A sub-agent's task is excluded by the conversation's kind, not here: its
- *   finish is in the child's log, and `ensureRun` never wakes a non-chat conversation;
+ * 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 task's trigger account can still send to the conversation (`canSend`);
- * - no other wake started in the last {@link WAKE_WINDOW_MS} (else `later`).
- * The boundary is the newest finish whose trigger account can send.
+ * - 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 candidates = await t
+    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"])
+        .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))
@@ -48,15 +58,35 @@ export async function wakeDecisionIn(t, conv, consumed, deploymentOn, canSend) {
         .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.trigger_account_id)) {
-            boundary = { seq: Number(c.seq), triggerAccountId: c.trigger_account_id };
+        if (await canSend(c.account)) {
+            boundary = { seq: Number(c.seq), triggerAccountId: c.account };
             break;
         }
     }
@@ -71,7 +101,7 @@ export async function wakeDecisionIn(t, conv, consumed, deploymentOn, canSend) {
         sql `floor(extract(epoch from now()) * 1000)::bigint`.as("now"),
     ])
         .where("r.conversation_id", "=", conv.id)
-        .where("w.type", "=", "background_task_finished")
+        .where("w.type", "in", WAKE_EVENT_TYPES)
         .executeTakeFirst();
     if (last?.started != null) {
         const windowEnd = Number(last.started) + WAKE_WINDOW_MS;

package/dist/background/wake.d.ts

@@ -4,24 +4,26 @@ 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). {@link BackgroundTaskFinisher} announces the committed
- * finish (`background_task.finished`, an in-process domain event: the finisher's module sits
- * below the runtime); {@link onFinished} asks the run queue for a run. The wake rules themselves
- * (own task, not reported, the wake setting, the queue not paused, the trigger account can still
- * send, 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. Provided by `RuntimeModule`.
+ * 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 subscription (the events may outlive this instance). */
+    /** 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 (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 finish
-     * at its next step instead, or its end starts the wake. Never throws.
+     * 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

@@ -13,39 +13,45 @@ 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). {@link BackgroundTaskFinisher} announces the committed
- * finish (`background_task.finished`, an in-process domain event: the finisher's module sits
- * below the runtime); {@link onFinished} asks the run queue for a run. The wake rules themselves
- * (own task, not reported, the wake setting, the queue not paused, the trigger account can still
- * send, 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. Provided by `RuntimeModule`.
+ * 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 subscription (the events may outlive this instance). */
+    /** 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));
+        this.unsubscribe = [
+            events.on("background_task.finished", ({ conversationId }) => this.onFinished(conversationId)),
+            events.on("subagent.delivered", ({ conversationId }) => this.onFinished(conversationId)),
+        ];
     }
     /**
-     * A task of `conversationId` finished (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 finish
-     * at its next step instead, or its end starts the wake. Never throws.
+     * 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 task wake failed", { conversationId, err });
+            this.log.warn("background wake failed", { conversationId, err });
         }
     }
     onApplicationShutdown() {
-        this.unsubscribe();
+        for (const off of this.unsubscribe)
+            off();
     }
 };
 BackgroundWake = __decorate([

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 {};