@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/catalog/plugin-install.js

@@ -7,12 +7,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { randomUUID } from "node:crypto";
-import { EXTENSION_POINTS, parseExtensionPoint, parseSkillMd, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { createHash, randomUUID } from "node:crypto";
+import { EXTENSION_POINTS, marketplaceEntryDeprecation, parseExtensionPoint, parseSkillMd, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { normalizeToolRef } from "../agents/definition.js";
-import { putTemplateVersionIn, revertTemplateVersionIn, softDeleteTemplateIn, } from "../agents/templates.js";
+import semver from "semver";
+import { revertTemplateVersionIn, softDeleteTemplateIn } from "../agents/templates.js";
 import { ApiError } from "../errors.js";
 import { isExtensionEnabled } from "../extensions/enabled.js";
 import { OrgExtensionConfigs, } from "../extensions/org-config.js";
@@ -28,11 +28,50 @@ import { OrgLock } from "../orgs/org-lock.js";
 import { packagePath } from "../packages/tgz.js";
 import { SkillsService, skillConflictError, skillConflicts, } from "../skills/skills.service.js";
 import { StorageService } from "../storage/storage.service.js";
+import { assertNotPlatformDefault, themesPreview, } from "../themes/theme-usage.js";
 import { ConnectorsService } from "../tools/connectors.service.js";
-import { findConnectorIn, lockOrgForActions, readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, requiredActions, skillOf, templateConnectorInput, templatePluginProblem, } from "./catalog-content.js";
-import { assertItemInstallable, CatalogRequestsService, disabledPluginItems, pluginItemDisabled, } from "./requests.service.js";
-import { upgradeInfo } from "./upgrade-targets.js";
+import { findConnectorIn, lockOrgForActions, readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, requiredActions, templateConnectorInput, templatePluginProblem, } from "./catalog-content.js";
+import { versionUsable } from "./catalog-items.js";
+import { agentDefinitionRefs, componentOn, connectorTemplateState, connectorTemplatesOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, referenceIds, switchOf, themeIdClashes, } from "./component-state.js";
+import { assertItemInstallable, disabledPluginItems, pluginItemDisabled, resolveRequestsByInstall, } from "./request-rules.js";
+import { visibleTo } from "./scope.js";
+import { ScopeNoLongerWanted, ScopeStillWanted, wantedByScope } from "./scope-state.js";
 import { maxSatisfying, satisfiesRange } from "./versions.js";
+/** The confirm hash of an uninstall preview: sha256 over its sorted JSON (the scheme of `diffHash`). */
+export function uninstallPreviewHash(p) {
+    const by = (xs) => [...xs].sort((a, b) => `${a.kind}:${a.ref}`.localeCompare(`${b.kind}:${b.ref}`));
+    return createHash("sha256")
+        .update(JSON.stringify({
+        ...p,
+        components: by(p.components),
+        kept: by(p.kept),
+        agents: [...p.agents]
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((a) => ({ ...a, uses: by(a.uses) })),
+    }))
+        .digest("hex");
+}
+/** Upserts the org's switch row of an item in the caller's transaction (the org lock is held). */
+export async function upsertOrgSwitch(db, orgId, itemId, enabled, actor) {
+    await db
+        .insertInto("catalog_item_org_switches")
+        .values({ item_id: itemId, org_id: orgId, enabled, updated_by: actor })
+        .onConflict((oc) => oc.columns(["item_id", "org_id"]).doUpdateSet({
+        enabled,
+        updated_by: actor,
+        updated_at: sql `now()`,
+    }))
+        .execute();
+}
+/** The kernel (actor null, the scope sync) never installs what needs the org's input. */
+export class NeedsOrgInput extends ApiError {
+    plugin;
+    constructor(plugin) {
+        super("internal", `Plugin ${plugin} needs the organization's input (connector templates); only a person can install it`);
+        this.plugin = plugin;
+    }
+}
+const systemNeedsInput = (name) => new NeedsOrgInput(name);
 /** How deep plugin dependencies may nest (the root plugin's dependencies are level 1). */
 export const DEPENDENCY_DEPTH_LIMIT = 10;
 /** A failed install step, carried up through the dependency installs to the root install. */
@@ -65,33 +104,66 @@ const installNotFound = () => new ApiError("plugin.install_not_found", "Plugin i
 const fail = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
 const isUniqueViolation = (e) => typeof e === "object" && e !== null && e.code === "23505";
 const unresolved = (name, range, why) => new ApiError("catalog.dependency_unresolved", `Dependency ${name}@${range} cannot be resolved: ${why}`, [{ dependency: name, range }]);
-const dependencyDisabled = (name) => new ApiError("catalog.dependency_disabled", `Dependency ${name} is disabled by the enterprise admin, so this plugin cannot be installed`, [{ dependency: name }]);
+const dependencyDisabled = (name) => new ApiError("catalog.dependency_disabled", `Dependency ${name} is disabled by the super admin, so this plugin cannot be installed`, [{ dependency: name }]);
 /**
- * The dependency `d` resolved against the catalog: the highest imported version (of the live item
- * with that name) satisfying its range. No such item or version -> `catalog.dependency_unresolved`;
- * the item disabled -> `catalog.dependency_disabled` (the enterprise admin's ban is not bypassed,
- * spec §10).
+ * The dependency `d` resolved against the catalog (ruling P2-17, one version per deployment): the
+ * dependency's platform version (`platform_synced_version`), which must satisfy its range; only
+ * while it has none yet (its first sync failed), the highest imported version satisfying the range
+ * that its marketplace does not deprecate, a stable one before a prerelease (the marketplace
+ * folding rule). No such item or version -> `catalog.dependency_unresolved`; the item disabled ->
+ * `catalog.dependency_disabled` (the super admin's ban is not bypassed, spec §10).
  */
 async function resolveOne(db, d) {
     const item = await db
         .selectFrom("catalog_items")
-        .select(["id", "policy"])
+        .select([
+        "id",
+        "disabled",
+        "platform_synced_version",
+        "marketplace_id",
+        "awaiting_confirmation",
+        "owner_org_id",
+        "latest_version",
+    ])
         .where("name", "=", d.name)
         .where("deleted_at", "is", null)
         .executeTakeFirst();
     if (!item) {
-        throw unresolved(d.name, d.version, "it is not in the enterprise catalog; ask the enterprise admin to import it");
+        throw unresolved(d.name, d.version, "it is not in the platform catalog; ask the super admin to import it");
     }
-    if (item.policy === "disabled")
+    if (item.disabled)
         throw dependencyDisabled(d.name);
+    // An org upload waiting for the super admin is no dependency target (ruling P3-9)
+    if (item.awaiting_confirmation) {
+        throw unresolved(d.name, d.version, "it waits for a super admin to confirm its extension");
+    }
     const versions = await db
         .selectFrom("catalog_item_versions")
-        .select(["version", "manifest", "imported_at"])
+        .select(["version", "manifest", "imported_at", "applied_at", "rejected_at"])
         .where("item_id", "=", item.id)
         .execute();
-    const v = maxSatisfying(versions.map((x) => ({ ...x, importedAt: x.imported_at })), d.version);
+    let v;
+    if (item.platform_synced_version !== null) {
+        v = versions.find((x) => x.version === item.platform_synced_version);
+        if (!v || !satisfiesRange(v.version, d.version)) {
+            throw unresolved(d.name, d.version, `its platform version ${item.platform_synced_version} does not satisfy the range; ask ` +
+                "the super admin to update it");
+        }
+    }
+    else {
+        const deprecated = await deprecatedVersions(db, d.name, item.marketplace_id);
+        // An org's plugin offers only its applied version: never one pending or rejected (P3-34),
+        // also once transferred to the platform (P3-52)
+        const candidates = versions
+            .filter((x) => versionUsable(x))
+            .filter((x) => item.owner_org_id === null || x.version === item.latest_version)
+            .filter((x) => !deprecated.has(x.version))
+            .map((x) => ({ ...x, importedAt: x.imported_at }));
+        v =
+            maxSatisfying(candidates.filter((x) => semver.prerelease(x.version) === null), d.version) ?? maxSatisfying(candidates, d.version);
+    }
     if (!v) {
-        throw unresolved(d.name, d.version, "no imported version satisfies the range; ask the enterprise admin to import one");
+        throw unresolved(d.name, d.version, "no imported version satisfies the range; ask the super admin to import one");
     }
     return {
         name: d.name,
@@ -101,10 +173,24 @@ async function resolveOne(db, d) {
         manifest: v.manifest,
     };
 }
+/** The versions of plugin `name` its marketplace (`marketplaceId`) marks deprecated. */
+async function deprecatedVersions(db, name, marketplaceId) {
+    if (marketplaceId === null)
+        return new Set();
+    const rows = await db
+        .selectFrom("marketplace_entries")
+        .select(["version", "entry"])
+        .where("source_id", "=", marketplaceId)
+        .where("name", "=", name)
+        .execute();
+    return new Set(rows
+        .filter((r) => marketplaceEntryDeprecation(r.entry) !== null)
+        .map((r) => r.version));
+}
 /**
- * Resolves a plugin's dependencies against the catalog: for each one the highest imported version
- * of the live item with that name satisfying its range. The whole dependency tree is checked: a
- * dependency nothing satisfies -> `catalog.dependency_unresolved`; a disabled one ->
+ * Resolves a plugin's dependencies against the catalog: for each one the platform version of the
+ * live item with that name, which must satisfy its range (see `resolveOne`). The whole dependency
+ * tree is checked: a dependency nothing satisfies -> `catalog.dependency_unresolved`; a disabled one ->
  * `catalog.dependency_disabled`; a cycle (`a` -> `b` -> `a`, by name) or nesting deeper than
  * {@link DEPENDENCY_DEPTH_LIMIT} -> `catalog.dependency_cycle`. Returns the direct dependencies.
  */
@@ -189,9 +275,11 @@ export function under(e, at) {
  *    not run it; already enabled is recorded created=false);
  * 3. connectors from the templates (credentials / clients go to secrets, default policies are
  *    recorded `policy_source 'template'`);
- * 4. the skills (an org skill of the same name from the same catalog item gets a new version,
- *    recorded created=false with skill_version; one of other provenance, the org's own or another
- *    item's, refuses the install while planning with `plugin.skill_conflict`, spec §9.2).
+ * The plugin's skills and agent templates are platform components (plugin scope phase 2): stored
+ * once for the deployment and on in the org while the plugin is, so an install writes no org rows
+ * for them; a skill name the org already uses (its own skill, another plugin's) refuses the install
+ * while planning with `plugin.skill_conflict` (spec §9.2, rule 10). Uninstall leaves the org copies
+ * earlier installs wrote (linked to the platform components by the migration).
  * Approval follows the installed plugin's policy only (spec §10): dependency components are
  * re-checked against the root item's policy and their own item's disabled state. Each component is
  * recorded in `plugin_install_components` as soon as it exists; if any step fails, the components
@@ -199,9 +287,10 @@ export function under(e, at) {
  * install is marked failed (error holds only the step and the error code) and 502
  * `plugin.install_failed` is thrown. Uninstall removes only components with created=true that
  * nothing else uses, and reports what it kept and why. No in-process state; the org row lock
- * serializes writes within one org. In-place upgrades are run by `PluginUpgrader`
- * (plugin-upgrade.ts), which reuses the planning, install and ledger methods here (the ones without
- * `private` are internal to the catalog, not an API).
+ * serializes writes within one org. There is no per-org upgrade: a platform plugin is updated
+ * once for the deployment (`PlatformPluginUpdater`, plugin-upgrade.ts, ruling F2); an install left
+ * `upgrading` by an earlier per-org upgrade is undone from its journal by the next uninstall. The
+ * methods without `private` are internal to the catalog, not an API.
  */
 let PluginInstaller = class PluginInstaller {
     kdb;
@@ -210,7 +299,6 @@ let PluginInstaller = class PluginInstaller {
     registry;
     skills;
     orgConfigs;
-    requests;
     config;
     connectors;
     log;
@@ -219,7 +307,7 @@ let PluginInstaller = class PluginInstaller {
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     orgLock, storage, 
     /** The loaded extensions and connectors of this replica (the extension registry). */
-    registry, skills, orgConfigs, requests, config, 
+    registry, skills, orgConfigs, config, 
     /** Org connectors: installs create, upgrade and remove them. */
     connectors, log, txHost) {
         this.kdb = kdb;
@@ -228,7 +316,6 @@ let PluginInstaller = class PluginInstaller {
         this.registry = registry;
         this.skills = skills;
         this.orgConfigs = orgConfigs;
-        this.requests = requests;
         this.config = config;
         this.connectors = connectors;
         this.log = log;
@@ -250,15 +337,20 @@ let PluginInstaller = class PluginInstaller {
     async preflight(orgId, actor, itemId, version) {
         const plan = await this.plan(orgId, actor, itemId, version, null, "", undefined);
         await this.assertNoSkillConflicts(orgId, plan);
+        await this.assertNoThemeClashes(orgId, itemId);
         return { actions: planActions(plan) };
     }
     async install(orgId, actor, itemId, version, input, opts = {}) {
+        const { switchOn, via, ...actorOpts } = opts;
         const plan = await this.plan(orgId, actor, itemId, version, input, "", undefined);
         await this.assertNoSkillConflicts(orgId, plan);
+        await this.assertNoThemeClashes(orgId, itemId);
         let installId;
         try {
-            installId = await this.execute(orgId, actor, plan, opts, {
+            installId = await this.execute(orgId, actor, plan, actorOpts, {
                 actions: planActions(plan),
+                ...(switchOn === true && { switchOn }),
+                ...(via !== undefined && { via }),
             });
         }
         catch (e) {
@@ -297,6 +389,39 @@ let PluginInstaller = class PluginInstaller {
         if (conflicts.length > 0)
             throw skillConflictError(conflicts);
     }
+    /**
+     * Refuses installing a plugin whose themes would come on in the org (they follow it) while
+     * another theme with the same id is on there (themes spec §6, rule 10): 409 `theme.id_taken`,
+     * details `[{ theme, orgId, themes, plugins }]`, before anything is written.
+     */
+    async assertNoThemeClashes(orgId, itemId) {
+        const themes = await loadComponents(this.db, "theme", { itemId });
+        if (themes.length === 0)
+            return;
+        const st = await loadScopeState(this.db, "theme", themes);
+        const conflicts = [];
+        for (const c of themes) {
+            const p = pluginFactsOf(st, c.itemId, orgId);
+            const listed = listedIn(st, c.id, orgId);
+            const sw = switchOf(st, c.id, orgId);
+            if (componentOn(c, p, listed, sw) ||
+                !componentOn(c, p && { ...p, installed: true }, listed, sw)) {
+                continue;
+            }
+            const clash = await themeIdClashes(this.db, orgId, c, c.name);
+            if (clash.length > 0) {
+                conflicts.push({
+                    theme: c.name,
+                    orgId,
+                    themes: clash.map((x) => x.id),
+                    plugins: clash.map((x) => x.plugin ?? "platform"),
+                });
+            }
+        }
+        if (conflicts.length > 0) {
+            throw new ApiError("theme.id_taken", `The plugin's themes would come on next to themes with the same id already on in this organization (${conflicts.map((c) => c.theme).join(", ")}); switch those themes off first`, conflicts);
+        }
+    }
     /** The connector checks of templates against what this replica loads right now. */
     templateDeps() {
         const versions = new Map(this.registry.manifests().map((m) => [m.name, m.version]));
@@ -332,9 +457,17 @@ let PluginInstaller = class PluginInstaller {
         if (!v)
             throw new ApiError("catalog.item_not_found", "Plugin version not found");
         const manifest = v.manifest;
-        const deps = await resolveDependencies(this.db, manifest);
+        const declared = await resolveDependencies(this.db, manifest);
         const extension = await this.planExtension(orgId, manifest);
-        const templates = await readCatalogTemplates(this.storage, v);
+        const allTemplates = await readCatalogTemplates(this.storage, v);
+        // Only the connector templates on in the org make connectors (ruling P2-6): one switched off
+        // there, outside its own scope or disabled is skipped (input given for it is ignored)
+        const on = await connectorTemplatesOn(this.db, orgId, itemId, allTemplates.map((t) => t.id));
+        const templates = allTemplates.filter((t) => on.has(t.id));
+        const deps = [
+            ...declared,
+            ...(await this.impliedProviders(orgId, manifest, templates, declared)),
+        ];
         const skillNames = await catalogSkillNames(this.storage, v, manifest);
         const agentTemplates = await readCatalogAgentTemplates(this.storage, v);
         const connectors = new Map();
@@ -346,8 +479,11 @@ let PluginInstaller = class PluginInstaller {
             }
         }
         else {
-            this.checkInput(manifest, templates, input, at);
+            this.checkInput(manifest, allTemplates, input, at);
             for (const ct of templates) {
+                // The kernel installs only what needs no org input (the scope sync's `needs_config` rule)
+                if (actor === null)
+                    throw systemNeedsInput(manifest.name);
                 connectors.set(ct.id, this.planConnector(actor, { itemId, version, name: manifest.name }, ct, input, at, approvedBy));
             }
         }
@@ -378,6 +514,64 @@ let PluginInstaller = class PluginInstaller {
             dependencies,
         };
     }
+    /**
+     * The providers of the templates' connector kinds as implied dependencies: a template whose
+     * `plugin` is neither this plugin, a declared dependency nor already enabled in the org makes that
+     * plugin a dependency (installed first, recorded like a declared one, so an uninstall hands it
+     * back). No such plugin offered by the catalog -> `connector.kind_unavailable` naming it, before
+     * anything is written.
+     */
+    async impliedProviders(orgId, manifest, templates, declared) {
+        const out = [];
+        const seen = new Set([manifest.name, ...declared.map((d) => d.name)]);
+        for (const ct of templates) {
+            const provider = ct.file.template.plugin;
+            if (seen.has(provider))
+                continue;
+            seen.add(provider);
+            // Not deployed: the not_deployed refusal of the plan's own checks says it
+            if (templatePluginProblem(this.templateDeps(), ct.file.template) !== undefined)
+                continue;
+            if (await isExtensionEnabled(this.db, orgId, provider))
+                continue;
+            const refuse = (why) => new ApiError("connector.kind_unavailable", `Connector template ${ct.id} needs the plugin ${provider}, which is not enabled in this organization: ${why}`);
+            let dep;
+            try {
+                const { manifest: _m, ...resolved } = await resolveOne(this.db, {
+                    name: provider,
+                    version: ct.file.template.pluginVersion ?? "*",
+                });
+                dep = resolved;
+            }
+            catch (e) {
+                if (!(e instanceof ApiError))
+                    throw e;
+                throw refuse(e.code === "catalog.dependency_unresolved"
+                    ? `${provider} is deployed but switched off here and the catalog has no entry to switch it on; ask the super admin to enable it`
+                    : `${provider} is not offered to this organization`);
+            }
+            // Scope: only a plugin offered to this org may be switched on for it (nothing more is said)
+            const item = await this.db
+                .selectFrom("catalog_items")
+                .select(["scope", "builtin"])
+                .where("id", "=", dep.itemId)
+                .executeTakeFirstOrThrow();
+            const listed = await this.db
+                .selectFrom("catalog_item_scope_orgs")
+                .select("item_id")
+                .where("item_id", "=", dep.itemId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (!visibleTo({ scope: item.builtin ? "all" : item.scope }, listed !== undefined)) {
+                throw refuse(`${provider} is not offered to this organization`);
+            }
+            if (await this.findLiveDependency(this.db, orgId, dep, false)) {
+                throw refuse(`${provider} is installed but switched off in this organization`);
+            }
+            out.push(dep);
+        }
+        return out;
+    }
     /**
      * The connector input of one template from the org's input (C30), checked without a connection:
      * the template's connector extension deployed, the input valid, the credential / OAuth client it
@@ -481,7 +675,7 @@ let PluginInstaller = class PluginInstaller {
      * as they are. Returns the install id.
      */
     async execute(orgId, actor, plan, opts, ctx) {
-        const { itemId, version, manifest } = plan;
+        const { itemId, manifest } = plan;
         // The install row (role and item policy re-checked under the lock; one live install per org
         // and item)
         const installId = randomUUID();
@@ -523,6 +717,7 @@ let PluginInstaller = class PluginInstaller {
                         actions: requiredActions(depPlan.manifest),
                         approvedBy,
                         parent: installId,
+                        ...(ctx.via !== undefined && { via: ctx.via }),
                     });
                 }
                 catch (e) {
@@ -551,6 +746,8 @@ let PluginInstaller = class PluginInstaller {
                 const ci = plan.connectors.get(ct.id);
                 if (!ci)
                     throw new ApiError("internal", `Connector template ${ct.id} was not planned`);
+                if (actor === null)
+                    throw systemNeedsInput(manifest.name);
                 const r = await this.connectors.create(orgId, actor, ci, opts.actorTokenId);
                 await record({
                     kind: "connector",
@@ -560,30 +757,8 @@ let PluginInstaller = class PluginInstaller {
                     templateId: ct.id,
                 });
             }
-            step = "agent_templates";
-            for (const a of plan.agentTemplates) {
-                await this.installAgentTemplate(orgId, plan, a.template, record);
-            }
-            step = "skills";
-            for (const s of manifest.skills ?? []) {
-                const files = await readCatalogFiles(this.storage, plan.row.object_prefix, plan.row.files, packagePath(s.path));
-                const r = await this.skills.createVersionFromFiles(orgId, actor, { ...skillOf(files), files }, {
-                    catalog: {
-                        itemId,
-                        version,
-                        ...(nested && { approvedBy }),
-                        format: plan.sourceFormat,
-                        suggestPinned: s.pinned === true,
-                    },
-                    ...opts,
-                });
-                await record({
-                    kind: "skill",
-                    ref: r.skill.id,
-                    created: r.created,
-                    skillVersion: r.created ? null : r.version,
-                });
-            }
+            // Skills and agent templates are platform components (plugin scope phase 2): stored once for
+            // the deployment and on in the org while the plugin is, so the install writes no org rows
             await this.markInstalled(orgId, actor, installId, plan, done, ctx, opts);
             return installId;
         }
@@ -620,18 +795,25 @@ let PluginInstaller = class PluginInstaller {
         const { itemId, version } = plan;
         const t = this.db;
         await lockOrgForActions(this.orgLock, orgId, actor, ctx.actions);
+        // The scope sync decided outside this lock: a person's switch-off or a scope change committed
+        // since then wins (nothing written, converged)
+        if (ctx.via === "scope" &&
+            ctx.approvedBy === undefined &&
+            !(await wantedByScope(t, orgId, itemId))) {
+            throw new ScopeNoLongerWanted(orgId, itemId);
+        }
         if (ctx.approvedBy !== undefined) {
             // A dependency disabled (or removed) since it was planned
             const own = await t
                 .selectFrom("catalog_items")
-                .select(["policy", "deleted_at"])
+                .select(["disabled", "deleted_at"])
                 .where("id", "=", itemId)
                 .forShare()
                 .executeTakeFirst();
             if (!own || own.deleted_at !== null) {
-                throw unresolved(plan.name, plan.version, "it was removed from the enterprise catalog");
+                throw unresolved(plan.name, plan.version, "it was removed from the platform catalog");
             }
-            if (own.policy === "disabled")
+            if (own.disabled)
                 throw dependencyDisabled(plan.name);
         }
         await assertItemInstallable(t, orgId, itemId, ctx.approvedBy ?? itemId);
@@ -663,34 +845,22 @@ let PluginInstaller = class PluginInstaller {
             throw e;
         }
     }
-    /**
-     * An agent template step: created (or a new version of the org's live template of this plugin and
-     * name) and recorded in one transaction of its own, under the org row lock.
-     */
-    async installAgentTemplate(orgId, plan, template, record) {
-        await this.orgLock.lock(orgId);
-        const r = await putTemplateVersionIn(this.db, {
-            orgId,
-            plugin: plan.name,
-            catalogItemId: plan.itemId,
-            catalogVersion: plan.version,
-            sourceFormat: plan.sourceFormat,
-        }, template);
-        await record({
-            kind: "agent_template",
-            ref: r.id,
-            created: r.created,
-            skillVersion: !r.created && r.changed ? r.version : null,
-        });
-    }
     /** The install `installed` and its `plugin.org_installed` audit, under the org row lock (its own transaction). */
     async markInstalled(orgId, actor, installId, plan, done, ctx, opts) {
         const { itemId, version } = plan;
         const t = this.db;
         await this.orgLock.lock(orgId);
+        // The platform version current at commit (one per deployment): a platform update that
+        // committed while this install ran moved the row already, or did not see it yet
         const updated = await t
             .updateTable("plugin_installs")
-            .set({ status: "installed" })
+            .set((eb) => ({
+            status: "installed",
+            version: eb.fn.coalesce(eb
+                .selectFrom("catalog_items as i")
+                .select("i.platform_synced_version")
+                .where("i.id", "=", itemId), eb.ref("plugin_installs.version")),
+        }))
             .where("id", "=", installId)
             .where("status", "=", "installing")
             .executeTakeFirst();
@@ -699,7 +869,11 @@ let PluginInstaller = class PluginInstaller {
         if (updated.numUpdatedRows === 0n) {
             throw new ApiError("plugin.install_not_found", "The install record was cleaned up as stale while the install was running");
         }
-        await this.requests.resolveByInstall(orgId, itemId, actor, opts);
+        await resolveRequestsByInstall(t, orgId, itemId, actor, opts);
+        // The org switch is written with the install, in one transaction under the org lock
+        if (ctx.switchOn === true && ctx.parent === undefined) {
+            await upsertOrgSwitch(t, orgId, itemId, true, actor);
+        }
         await audit(t, {
             actorAccountId: actor,
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
@@ -712,6 +886,8 @@ let PluginInstaller = class PluginInstaller {
                 version,
                 components: done,
                 ...(ctx.parent !== undefined && { dependencyOf: ctx.parent }),
+                ...(ctx.via !== undefined && { via: ctx.via }),
+                ...opts.auditDetail,
             },
         });
     }
@@ -740,6 +916,8 @@ let PluginInstaller = class PluginInstaller {
                 rolledBack: done,
                 rollbackErrors,
                 ...(ctx.parent !== undefined && { dependencyOf: ctx.parent }),
+                ...(ctx.via !== undefined && { via: ctx.via }),
+                ...opts.auditDetail,
             },
         });
     }
@@ -754,7 +932,7 @@ let PluginInstaller = class PluginInstaller {
             return null;
         const name = manifest.name;
         if (!this.registry.manifests().some((m) => m.name === name)) {
-            throw new ApiError("catalog.not_deployed", `The extension of plugin ${name} is not deployed; ask the enterprise admin to install and enable it`);
+            throw new ApiError("catalog.not_deployed", `The extension of plugin ${name} is not running on the platform (not installed, waiting for its deployment config or permission approval, disabled, or failed to load); the org cannot switch it on until it runs`);
         }
         const enabled = await isExtensionEnabled(this.db, orgId, name);
         if (!enabled && (await disabledPluginItems(this.db, [name])).length > 0) {
@@ -864,6 +1042,13 @@ let PluginInstaller = class PluginInstaller {
         }
         if (c.kind === "plugin")
             return false;
+        // A row the org promoted is the org's own shared item (ruling P3-47): an install never
+        // removes or reverts it (P3-46 keeps plugin content from being promoted; this guards rows
+        // recorded before that or by a legacy install)
+        if ((c.kind === "agent_template" || c.kind === "skill") &&
+            (await promotedOrgRow(t, orgId, c.kind, c.ref))) {
+            return false;
+        }
         if (c.kind === "agent_template") {
             if (c.created)
                 return softDeleteTemplateIn(t, orgId, c.ref);
@@ -901,25 +1086,83 @@ let PluginInstaller = class PluginInstaller {
      * (a replica crashed midway) - the last two are cleaned up as a rollback (versions added to
      * existing skills are reverted too). Still installing -> `plugin.install_in_progress`.
      */
-    async uninstall(orgId, actor, installId, opts = {}) {
+    async uninstall(orgId, actor, installId, opts = {}, sw) {
         if (!UUID_RE.test(installId))
             throw installNotFound();
-        return this.writeUninstall(orgId, actor, installId, opts);
+        return this.writeUninstall(orgId, actor, installId, opts, sw);
     }
-    /** The uninstall's one transaction; the extensions it disabled are notified once it commits. */
-    async writeUninstall(orgId, actor, installId, opts) {
+    /**
+     * The uninstall's one transaction; the extensions it disabled are notified once it commits. A
+     * scope sync uninstall (`via: "scope"`) re-checks under the org row lock that the item is still
+     * not wanted in the org and that no other live install depends on it ({@link ScopeStillWanted},
+     * nothing written), and keeps the connectors it created as the org's own (`org_owned`).
+     */
+    async writeUninstall(orgId, actor, installId, opts, sw) {
+        const { via, ...actorOpts } = opts;
         const report = { removed: [], kept: [] };
+        let itemId;
+        if (via === "scope") {
+            // A person's switch-on (or a scope change) committed after the sync's decision wins
+            await this.orgLock.lock(orgId);
+            const row = await this.db
+                .selectFrom("plugin_installs")
+                .select("item_id")
+                .where("id", "=", installId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (row !== undefined &&
+                ((await wantedByScope(this.db, orgId, row.item_id)) ||
+                    (await this.heir(orgId, new Set([installId]), "plugin", installId)) !== undefined)) {
+                throw new ScopeStillWanted(orgId, row.item_id);
+            }
+        }
+        if (sw !== undefined) {
+            // Switching off: the org lock first, then the preview is re-checked and the switch row is
+            // written in this same transaction
+            await this.orgLock.lock(orgId);
+            const row = await this.db
+                .selectFrom("plugin_installs")
+                .select("item_id")
+                .where("id", "=", installId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            itemId = row?.item_id;
+            // The item row FOR SHARE, as a switch without an uninstall takes it: an owner's delete or
+            // transfer (FOR UPDATE) decides on who uses it
+            if (itemId !== undefined) {
+                await this.db
+                    .selectFrom("catalog_items")
+                    .select("id")
+                    .where("id", "=", itemId)
+                    .forShare()
+                    .executeTakeFirst();
+            }
+            if (sw.expectHash !== undefined && row !== undefined) {
+                const now = uninstallPreviewHash(await this.previewUninstall(orgId, installId));
+                if (now !== sw.expectHash) {
+                    throw new ApiError("plugin.switch_stale", "The uninstall preview changed; review it and confirm again");
+                }
+            }
+        }
+        // An org's own uninstall never takes the platform default theme away from it (themes spec §7;
+        // a scope sync uninstall follows a scope change or disable that was guarded already)
+        if (via !== "scope")
+            await this.assertKeepsPlatformDefault(orgId, installId);
         const outcome = await this.uninstallIn(orgId, actor, installId, {
             report,
             removing: new Set(),
             authorize: true,
-            opts,
+            opts: actorOpts,
+            ...(via !== undefined && { via }),
         });
         if (outcome === "missing")
             throw installNotFound();
         if (outcome === "kept") {
             report.kept.push({ kind: "plugin", ref: installId, reason: "used_by_other_install" });
         }
+        if (itemId !== undefined && outcome === "removed") {
+            await upsertOrgSwitch(this.db, orgId, itemId, false, actor);
+        }
         afterCommit(async () => {
             for (const r of report.removed) {
                 if (r.kind === "extension")
@@ -928,6 +1171,24 @@ let PluginInstaller = class PluginInstaller {
         });
         return report;
     }
+    /**
+     * 409 `theme.platform_default` when uninstalling `installId` would switch the platform default
+     * theme off in the org (one of the plugin's `follow` themes on there through it, themes spec §7),
+     * in the caller's transaction before anything is written. A missing install passes (the
+     * uninstall reports it).
+     */
+    async assertKeepsPlatformDefault(orgId, installId) {
+        const found = await this.db
+            .selectFrom("plugin_installs")
+            .select("id")
+            .where("id", "=", installId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!found)
+            return;
+        const p = await this.previewUninstall(orgId, installId);
+        await assertNotPlatformDefault(this.db, (p.themes ?? []).map((t) => t.id), () => "narrower");
+    }
     /**
      * The oldest other live install (not in `removing`) that has component `kind` / `ref`, or
      * undefined.
@@ -1007,6 +1268,11 @@ let PluginInstaller = class PluginInstaller {
             .executeTakeFirst();
         if (!row)
             return "missing";
+        // A dependency its own scope still wants on in the org stays as a standalone install (the
+        // dependent's component row goes with the dependent's install row)
+        if (ctx.from !== undefined && (await wantedByScope(t, orgId, row.item_id))) {
+            return "wanted_by_scope";
+        }
         // Another install outside this uninstall depends on it: kept (a dependency uninstall hands
         // ownership over)
         const user = await this.heir(orgId, new Set([...removing, installId]), "plugin", installId);
@@ -1072,6 +1338,10 @@ let PluginInstaller = class PluginInstaller {
                 created = now.created;
             }
             const comp = { kind: c.kind, ref: c.ref, created, skillVersion: c.skill_version };
+            // Skills and agent templates of earlier installs (org copies, now linked to the platform
+            // components, phase 2) stay: the plugin's components go off in the org with the install
+            if ((c.kind === "skill" || c.kind === "agent_template") && !rollbackMode)
+                continue;
             if (!created) {
                 // Rollback cleanup: a version this install added to an existing skill is reverted; other
                 // pre-existing components are kept
@@ -1091,6 +1361,14 @@ let PluginInstaller = class PluginInstaller {
                     addRemoved({ kind: "plugin", ref: c.ref });
                 else if (outcome === "kept")
                     keep("used_by_other_install");
+                else if (outcome === "wanted_by_scope")
+                    keep("wanted_by_scope");
+                continue;
+            }
+            // A scope sync uninstall leaves the connectors to the org (spec §5 rule 8): the component row
+            // goes with the install row, so nothing removes them later
+            if (c.kind === "connector" && ctx.via === "scope" && !rollbackMode) {
+                keep("org_owned");
                 continue;
             }
             const reason = rollbackMode ? "plugin_install_cleanup" : (ctx.reason ?? "plugin_uninstall");
@@ -1115,6 +1393,8 @@ let PluginInstaller = class PluginInstaller {
                 removed: mine.removed,
                 kept: mine.kept,
                 ...(ctx.from !== undefined && { dependencyOf: ctx.from }),
+                ...(ctx.via !== undefined && { via: ctx.via }),
+                ...ctx.opts.auditDetail,
             },
         });
         return "removed";
@@ -1189,7 +1469,6 @@ let PluginInstaller = class PluginInstaller {
         const rows = await q.orderBy("a.installed_at", "desc").orderBy("a.id").execute();
         if (rows.length === 0)
             return [];
-        const info = await upgradeInfo(this.db, this.registry, rows.map((r) => ({ itemId: r.item_id, name: r.name, version: r.version })));
         const comps = await this.db
             .selectFrom("plugin_install_components")
             .select(["install_id", "kind", "ref", "created", "skill_version", "dropped"])
@@ -1213,8 +1492,8 @@ let PluginInstaller = class PluginInstaller {
                 skillVersion: c.skill_version,
                 dropped: c.dropped,
             })),
-            upgradeAvailable: info.get(`${r.item_id}@${r.version}`)?.upgradeAvailable ?? null,
-            deploymentPending: info.get(`${r.item_id}@${r.version}`)?.deploymentPending ?? false,
+            upgradeAvailable: null,
+            deploymentPending: false,
         }));
     }
     /**
@@ -1276,6 +1555,288 @@ let PluginInstaller = class PluginInstaller {
         }
         return removed;
     }
+    /**
+     * Installs the dependencies an installed plugin's version declares and the org lacks (rule 9),
+     * as the kernel (actor null): a platform update can add one. Each is recorded on the install
+     * as a `plugin` component (created when this installed it, so an uninstall takes it along). One
+     * that needs the org's input (connector templates) is left out and its name returned. A
+     * dependency already installed in the org is recorded as it is (created false).
+     */
+    async addMissingDependencies(orgId, installId) {
+        const row = await this.db
+            .selectFrom("plugin_installs as a")
+            .innerJoin("catalog_item_versions as v", (j) => j.onRef("v.item_id", "=", "a.item_id").onRef("v.version", "=", "a.version"))
+            .select(["a.item_id", "a.status", "v.manifest"])
+            .where("a.id", "=", installId)
+            .where("a.org_id", "=", orgId)
+            .executeTakeFirst();
+        if (row?.status !== "installed")
+            return [];
+        const record = async (c) => {
+            await this.db
+                .insertInto("plugin_install_components")
+                .values({
+                install_id: installId,
+                kind: c.kind,
+                ref: c.ref,
+                created: c.created,
+                skill_version: null,
+            })
+                .onConflict((oc) => oc.columns(["install_id", "kind", "ref"]).doNothing())
+                .execute();
+        };
+        const needsInput = [];
+        for (const dep of await resolveDependencies(this.db, row.manifest)) {
+            if ((await this.recordDependency(orgId, dep, record)) !== undefined)
+                continue;
+            let plan;
+            try {
+                plan = await this.plan(orgId, null, dep.itemId, dep.version, {}, "", row.item_id);
+            }
+            catch (e) {
+                if (e instanceof NeedsOrgInput) {
+                    needsInput.push(dep.name);
+                    continue;
+                }
+                throw e;
+            }
+            const child = await this.execute(orgId, null, plan, {}, {
+                actions: requiredActions(plan.manifest),
+                approvedBy: row.item_id,
+                parent: installId,
+                via: "scope",
+            });
+            await this.recordDependency(orgId, dep, record, child);
+        }
+        return needsInput;
+    }
+    /**
+     * The connector templates of an installed plugin that are on in the org (ruling P2-6) and have
+     * no live connector there: made from the platform template (`platform_template_id`) or recorded
+     * on the install (`template_id`). The org's plugin is `needs_config` while any is missing (ruling
+     * P2-10). Empty for a plugin not installed.
+     */
+    async missingConnectors(orgId, itemId) {
+        const a = await this.db
+            .selectFrom("plugin_installs as a")
+            .innerJoin("catalog_item_versions as v", (j) => j.onRef("v.item_id", "=", "a.item_id").onRef("v.version", "=", "a.version"))
+            .select(["a.id", "a.version", "v.manifest", "v.object_prefix", "v.files"])
+            .where("a.org_id", "=", orgId)
+            .where("a.item_id", "=", itemId)
+            .where("a.status", "=", "installed")
+            .executeTakeFirst();
+        if (!a)
+            return undefined;
+        if ((a.manifest.connectorTemplates ?? []).length === 0) {
+            return { installId: a.id, version: a.version, templates: [] };
+        }
+        const all = await readCatalogTemplates(this.storage, a);
+        const on = await connectorTemplatesOn(this.db, orgId, itemId, all.map((t) => t.id));
+        const made = new Set((await this.db
+            .selectFrom("connectors as c")
+            .innerJoin("platform_connector_templates as p", "p.id", "c.platform_template_id")
+            .select("p.template_id")
+            .where("c.org_id", "=", orgId)
+            .where("c.deleted_at", "is", null)
+            .where("p.catalog_item_id", "=", itemId)
+            .execute()).map((r) => r.template_id));
+        const recorded = await this.db
+            .selectFrom("plugin_install_components as l")
+            .innerJoin("connectors as c", (j) => j.on(sql `c.id::text`, "=", sql `l.ref`))
+            .select("l.template_id")
+            .where("l.install_id", "=", a.id)
+            .where("l.kind", "=", "connector")
+            .where("c.deleted_at", "is", null)
+            .execute();
+        for (const r of recorded)
+            if (r.template_id !== null)
+                made.add(r.template_id);
+        return {
+            installId: a.id,
+            version: a.version,
+            templates: all.filter((t) => on.has(t.id) && !made.has(t.id)),
+        };
+    }
+    /**
+     * Creates the connectors an installed plugin is missing (ruling P2-10, `POST …/catalog/:itemId/
+     * connectors`): `input.connectors` names some of {@link missingConnectors}' templates with the
+     * same input as an install (endpoint, credential or OAuth client); each is created as at install
+     * and recorded on the install. Returns the created connectors by template.
+     */
+    async configureConnectors(orgId, actor, itemId, input, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw installNotFound();
+        const missing = await this.missingConnectors(orgId, itemId);
+        if (!missing)
+            throw installNotFound();
+        const keys = Object.keys(input.connectors ?? {});
+        if (keys.length === 0) {
+            throw new ApiError("validation_failed", "Request validation failed", [
+                { path: "connectors", message: "Give the input of at least one missing connector" },
+            ]);
+        }
+        for (const k of keys) {
+            if (!missing.templates.some((t) => t.id === k)) {
+                throw new ApiError("validation_failed", "Request validation failed", [
+                    {
+                        path: `connectors.${k}`,
+                        message: "No connector of this template is missing in this organization",
+                    },
+                ]);
+            }
+        }
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select("name")
+            .where("id", "=", itemId)
+            .executeTakeFirstOrThrow();
+        const plans = missing.templates
+            .filter((t) => keys.includes(t.id))
+            .map((t) => ({
+            id: t.id,
+            ci: this.planConnector(actor, { itemId, version: missing.version, name: item.name }, t, input, "", undefined),
+        }));
+        const out = [];
+        for (const p of plans) {
+            const r = await this.connectors.create(orgId, actor, p.ci, opts.actorTokenId);
+            await this.recordConnector(missing.installId, r.connector.id, p.id);
+            out.push({ templateId: p.id, connectorId: r.connector.id });
+        }
+        return out;
+    }
+    /** A configured connector's ledger row (its own transaction). */
+    async recordConnector(installId, ref, templateId) {
+        await this.db
+            .insertInto("plugin_install_components")
+            .values({
+            install_id: installId,
+            kind: "connector",
+            ref,
+            created: true,
+            skill_version: null,
+            template_id: templateId,
+        })
+            .onConflict((oc) => oc.columns(["install_id", "kind", "ref"]).doNothing())
+            .execute();
+    }
+    /**
+     * One more connector from a platform connector template on in the org (rulings P4-7, P4-T6-8;
+     * `POST …/connector-templates/:templateId/connectors`): `templateId` is the platform connector
+     * template's id; `config` is an install's connector input (endpoint, credential or OAuth client,
+     * slug) and `name` its name. Without a slug the name and slug default to the first free ones,
+     * chosen by the create under the org lock after its outbound calls
+     * (`CreateConnectorInput.slugDefault`); only a given slug answers 409 `connector.slug_taken`. Created as at install ({@link planConnector}, then
+     * `ConnectorsService.create`, which checks the slug before any outbound call and re-checks it,
+     * `connectors.manage`, the item and the template being on under the org lock), linked to the
+     * template, and recorded on the plugin's live install in the org when there is one. A template
+     * that is missing, deleted or not offered to the org -> 404 `component.not_found`; offered but
+     * off there (its plugin not installed, or switched off) -> 409 `component.off`; input errors ->
+     * 400 `validation_failed` at `config.<field>`.
+     */
+    async addTemplateConnector(orgId, actor, templateId, input, opts = {}) {
+        const notFound = () => new ApiError("component.not_found", "The connector template does not exist or is not available in this organization");
+        if (!UUID_RE.test(templateId))
+            throw notFound();
+        // read here to fail early, and again under the org lock by the create (`mustBeOn`)
+        const state = await connectorTemplateState(this.db, orgId, templateId);
+        if (state === "absent")
+            throw notFound();
+        if (state === "off") {
+            throw new ApiError("component.off", "This connector template is off in this organization; switch it (or its plugin) on first");
+        }
+        const row = await this.db
+            .selectFrom("platform_connector_templates as t")
+            .innerJoin("catalog_items as i", "i.id", "t.catalog_item_id")
+            .leftJoin("plugin_installs as a", (j) => j
+            .onRef("a.item_id", "=", "t.catalog_item_id")
+            .on("a.org_id", "=", orgId)
+            .on("a.status", "=", "installed"))
+            .select([
+            "t.template_id",
+            "t.catalog_item_id",
+            "t.file",
+            "i.name",
+            "i.latest_version",
+            "a.version",
+        ])
+            .where("t.id", "=", templateId)
+            .executeTakeFirstOrThrow();
+        const ct = { id: row.template_id, file: row.file };
+        const at = `connectors.${ct.id}`;
+        // the paths of an install's input and of the create, under `config` here (`name` stays)
+        const rebase = (e) => {
+            if (!(e instanceof ApiError) || e.code !== "validation_failed" || !e.details)
+                return e;
+            return new ApiError(e.code, e.message, e.details.map((d) => {
+                const path = d.path;
+                if (typeof path !== "string")
+                    return d;
+                const rest = path === at || path.startsWith(`${at}.`) ? path.slice(at.length + 1) : path;
+                if (!/^(slug|credential|endpoint|client)(\.|$)/.test(rest)) {
+                    return rest === path ? d : { ...d, path: rest };
+                }
+                return { ...d, path: `config.${rest}` };
+            }));
+        };
+        const display = ct.file.displayName?.en ?? ct.id;
+        // a slug given by the caller is theirs (409 when taken); otherwise the create picks the first
+        // free default under the org lock, after its outbound calls (no retry repeats them)
+        const defaulted = input.config.slug === undefined;
+        let ci;
+        try {
+            ci = this.planConnector(actor, { itemId: row.catalog_item_id, version: row.version ?? row.latest_version, name: row.name }, ct, {
+                connectors: {
+                    [ct.id]: { ...input.config, ...(input.name !== undefined && { name: input.name }) },
+                },
+            }, "", undefined);
+        }
+        catch (e) {
+            throw rebase(e);
+        }
+        ci = {
+            ...ci,
+            template: ci.template && { ...ci.template, mustBeOn: true },
+            ...(defaulted && {
+                slugDefault: { display, ...(input.name !== undefined && { name: input.name }) },
+            }),
+        };
+        try {
+            const r = await this.connectors.create(orgId, actor, ci, opts.actorTokenId);
+            await this.recordOnLiveInstall(orgId, row.catalog_item_id, r.connector.id, ct.id);
+            return r;
+        }
+        catch (e) {
+            throw rebase(e);
+        }
+    }
+    /**
+     * Records a connector made from a plugin's template on the org's live install of that plugin,
+     * when there is one, under the org lock (so an uninstall in between is seen).
+     */
+    async recordOnLiveInstall(orgId, itemId, connectorId, templateId) {
+        await this.orgLock.lock(orgId);
+        const install = await this.db
+            .selectFrom("plugin_installs")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("item_id", "=", itemId)
+            .where("status", "=", "installed")
+            .executeTakeFirst();
+        if (!install)
+            return;
+        await this.db
+            .insertInto("plugin_install_components")
+            .values({
+            install_id: install.id,
+            kind: "connector",
+            ref: connectorId,
+            created: true,
+            skill_version: null,
+            template_id: templateId,
+        })
+            .onConflict((oc) => oc.columns(["install_id", "kind", "ref"]).doNothing())
+            .execute();
+    }
     /** The connector kinds an extension provides (the `connector@1` implementations loaded on this replica). */
     connectorKindsOf(plugin) {
         return this.registry
@@ -1285,36 +1846,142 @@ let PluginInstaller = class PluginInstaller {
             .filter((k) => typeof k === "string");
     }
     /**
-     * The connectors, org skills and agent templates (`subagents.templates`) referenced by the
-     * current definitions of the org's live agents.
+     * The uninstall preview of an install (see {@link UninstallPreview}); the real uninstall may keep
+     * more (another install using a component, a connector still using an extension). The plugin's
+     * skills and agent templates are platform components (phase 2): the ones on in the org through
+     * the plugin (`follow`) go off with it, so the agents using them (by the platform id or an
+     * unpinned org copy linked to it) are listed, also for the dependency installs it created that
+     * go with it; ledger rows of earlier installs' org copies are not removed and not listed (an
+     * uninstall keeps legacy copies, like the platform update keeps copies of removed components).
      */
-    async agentRefs(orgId) {
-        const rows = await this.db
-            .selectFrom("agents as a")
-            .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
-            .select("v.definition")
+    async previewUninstall(orgId, installId) {
+        if (!UUID_RE.test(installId))
+            throw installNotFound();
+        const t = this.db;
+        const row = await t
+            .selectFrom("plugin_installs as a")
+            .innerJoin("catalog_items as i", "i.id", "a.item_id")
+            .select(["a.id", "a.item_id", "a.version", "i.name"])
+            .where("a.id", "=", installId)
             .where("a.org_id", "=", orgId)
-            .where("a.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!row)
+            throw installNotFound();
+        const ledger = (id) => t
+            .selectFrom("plugin_install_components")
+            .select(["kind", "ref", "created"])
+            .where("install_id", "=", id)
+            .orderBy("kind")
+            .orderBy("ref")
             .execute();
-        const connectors = new Set();
-        const skills = new Set();
-        const templates = new Set();
-        for (const r of rows) {
-            const def = r.definition;
-            for (const ref of def?.tools ?? []) {
-                const n = normalizeToolRef(ref);
-                if (n?.kind === "connector" && typeof n.connectorId === "string") {
-                    connectors.add(n.connectorId);
+        const comps = (await ledger(installId)).filter((c) => c.kind !== "skill" && c.kind !== "agent_template");
+        const agents = await agentDefinitionRefs(t, orgId);
+        const used = new Map();
+        const use = (a, kind, ref) => {
+            const e = used.get(a.id) ?? { id: a.id, name: a.name, uses: [] };
+            if (!e.uses.some((u) => u.kind === kind && u.ref === ref))
+                e.uses.push({ kind, ref });
+            used.set(a.id, e);
+        };
+        const kept = [];
+        /**
+         * The agents using what goes with an install: connectors it created (they stay, kept for the
+         * agents) and the plugin's platform skills and agent templates on in the org through it
+         * (`follow`; by the platform id or an unpinned org copy linked to it). Dependency installs it
+         * created go with it unless their own scope wants them (Task 7: their components count too).
+         */
+        const visit = async (itemId, rows, top, seen) => {
+            for (const c of rows) {
+                if (!c.created) {
+                    if (top)
+                        kept.push({ kind: c.kind, ref: c.ref, reason: "pre_existing" });
+                    continue;
+                }
+                if (c.kind === "plugin") {
+                    const dep = await t
+                        .selectFrom("plugin_installs")
+                        .select("item_id")
+                        .where("id", "=", c.ref)
+                        .where("org_id", "=", orgId)
+                        .executeTakeFirst();
+                    if (!dep)
+                        continue;
+                    if (await wantedByScope(t, orgId, dep.item_id)) {
+                        if (top)
+                            kept.push({ kind: c.kind, ref: c.ref, reason: "wanted_by_scope" });
+                        continue;
+                    }
+                    if (seen.has(c.ref))
+                        continue;
+                    seen.add(c.ref);
+                    const sub = (await ledger(c.ref)).filter((x) => x.kind !== "skill" && x.kind !== "agent_template");
+                    await visit(dep.item_id, sub, false, seen);
+                    continue;
+                }
+                if (c.kind !== "connector")
+                    continue;
+                const users = agents.filter((a) => a.connectors.has(c.ref));
+                if (users.length === 0)
+                    continue;
+                if (top)
+                    kept.push({ kind: c.kind, ref: c.ref, reason: "used_by_agents" });
+                for (const a of users)
+                    use(a, c.kind, c.ref);
+            }
+            for (const kind of ["skill", "agent_template"]) {
+                const platform = await loadComponents(t, kind, { itemId });
+                const st = await loadScopeState(t, kind, platform);
+                const off = platform.filter((c) => c.scopeMode === "follow" &&
+                    componentOn(c, pluginFactsOf(st, c.itemId, orgId), listedIn(st, c.id, orgId), switchOf(st, c.id, orgId)));
+                const refs = await referenceIds(t, orgId, kind, off.map((c) => c.id));
+                for (const a of agents) {
+                    for (const ref of kind === "skill" ? a.skills : a.templates) {
+                        if (refs.has(ref))
+                            use(a, kind, ref);
+                    }
+                }
+            }
+            const themes = await loadComponents(t, "theme", { itemId });
+            const tst = await loadScopeState(t, "theme", themes);
+            for (const c of themes) {
+                if (c.scopeMode === "follow" &&
+                    componentOn(c, pluginFactsOf(tst, c.itemId, orgId), listedIn(tst, c.id, orgId), switchOf(tst, c.id, orgId))) {
+                    lostThemes.set(c.id, new Set([orgId]));
                 }
             }
-            for (const s of def?.skills?.orgSkills ?? [])
-                if (typeof s === "string")
-                    skills.add(s);
-            for (const x of def?.subagents?.templates ?? [])
-                if (typeof x === "string")
-                    templates.add(x);
-        }
-        return { connectors, skills, templates };
+        };
+        /** The themes that go off in the org with the install (and the dependencies it removes). */
+        const lostThemes = new Map();
+        await visit(row.item_id, comps, true, new Set([installId]));
+        const themes = await themesPreview(t, lostThemes);
+        return {
+            installId,
+            name: row.name,
+            version: row.version,
+            components: comps.map((c) => ({ kind: c.kind, ref: c.ref, created: c.created })),
+            kept,
+            agents: [...used.values()]
+                .map((a) => ({ ...a, uses: a.uses.sort((x, y) => x.ref.localeCompare(y.ref)) }))
+                .sort((x, y) => x.id.localeCompare(y.id)),
+            ...(themes !== undefined && { themes }),
+        };
+    }
+    /**
+     * The connectors, skills (selected, pinned, or in an inline sub-agent template) and agent
+     * templates (`subagents.templates`) referenced by the current definitions of the org's live
+     * agents.
+     */
+    async agentRefs(orgId) {
+        const out = { connectors: new Set(), skills: new Set(), templates: new Set() };
+        for (const a of await agentDefinitionRefs(this.db, orgId)) {
+            for (const x of a.connectors)
+                out.connectors.add(x);
+            for (const x of a.skills)
+                out.skills.add(x);
+            for (const x of a.templates)
+                out.templates.add(x);
+        }
+        return out;
     }
 };
 __decorate([
@@ -1326,9 +1993,6 @@ __decorate([
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], PluginInstaller.prototype, "createInstallRow", null);
-__decorate([
-    Transactional({ propagation: "requires_new" })
-], PluginInstaller.prototype, "installAgentTemplate", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], PluginInstaller.prototype, "markInstalled", null);
@@ -1359,6 +2023,12 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], PluginInstaller.prototype, "undoUpgradeIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginInstaller.prototype, "recordConnector", null);
+__decorate([
+    Transactional()
+], PluginInstaller.prototype, "recordOnLiveInstall", null);
 PluginInstaller = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
@@ -1367,11 +2037,10 @@ PluginInstaller = __decorate([
     __param(3, Inject(ExtensionRegistry)),
     __param(4, Inject(SkillsService)),
     __param(5, Inject(OrgExtensionConfigs)),
-    __param(6, Inject(CatalogRequestsService)),
-    __param(7, Inject(KernelConfigService)),
-    __param(8, Inject(ConnectorsService)),
-    __param(9, Inject(KERNEL_LOGGER)),
-    __param(10, Inject(TransactionHost))
+    __param(6, Inject(KernelConfigService)),
+    __param(7, Inject(ConnectorsService)),
+    __param(8, Inject(KERNEL_LOGGER)),
+    __param(9, Inject(TransactionHost))
 ], PluginInstaller);
 export { PluginInstaller };
 /**
@@ -1483,3 +2152,36 @@ function orderByRequires(set) {
     }
     return placed;
 }
+/**
+ * Whether org row `id` (a skill or an agent template of the org) is linked without a pin to a live
+ * platform row the org promoted when sharing it (ruling P3-3): owned by the org and from no plugin
+ * (`catalog_item_id` null). A component of the org's own uploaded plugin is a plugin's, so its
+ * install copies are removed and reverted as any plugin's.
+ */
+async function promotedOrgRow(db, orgId, kind, id) {
+    const row = kind === "skill"
+        ? await db
+            .selectFrom("skills as s")
+            .innerJoin("platform_skills as p", "p.id", "s.platform_skill_id")
+            .select("s.id")
+            .where("s.id", "=", id)
+            .where("s.org_id", "=", orgId)
+            .where("s.pinned_version", "is", null)
+            .where("p.owner_org_id", "=", orgId)
+            // promoted, not an org plugin's component (which has its plugin, P3-2)
+            .where("p.catalog_item_id", "is", null)
+            .where("p.deleted_at", "is", null)
+            .executeTakeFirst()
+        : await db
+            .selectFrom("agent_templates as a")
+            .innerJoin("platform_agent_templates as p", "p.id", "a.platform_template_id")
+            .select("a.id")
+            .where("a.id", "=", id)
+            .where("a.org_id", "=", orgId)
+            .where("a.pinned_version", "is", null)
+            .where("p.owner_org_id", "=", orgId)
+            .where("p.catalog_item_id", "is", null)
+            .where("p.deleted_at", "is", null)
+            .executeTakeFirst();
+    return row !== undefined;
+}