@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/catalog/plugin-install.d.ts

@@ -1,15 +1,21 @@
-import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type Logger, type PluginManifest } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelDatabase, KernelDb, SourceFormat } from "../db/kernel-schema.js";
-import type { ExtensionHost } from "../extensions/host.js";
-import type { OrgExtensionConfigs } from "../extensions/org-config.js";
+import { type AgentTemplate, type ConnectorTemplateFile, type ConnectorTemplateSpec, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb, SourceFormat } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import { OrgExtensionConfigs, type OrgExtensionInput, type OrgExtensionPutOptions } from "../extensions/org-config.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import type { OrgAction } from "../orgs/roles.js";
-import { type SkillConflict, type SkillsService } from "../skills/skills.service.js";
-import type { StorageService } from "../storage/storage.service.js";
-import type { ConnectorsService, CreateConnectorInput } from "../tools/connectors.service.js";
-import { type CatalogVersionFiles, type TemplateDeps } from "./org-catalog.service.js";
-import { type CatalogRequestsService } from "./requests.service.js";
-type Trx = Transaction<KernelDatabase>;
+import { type SkillConflict, SkillsService } from "../skills/skills.service.js";
+import { StorageService } from "../storage/storage.service.js";
+import { type ThemePreview } from "../themes/theme-usage.js";
+import type { ConnectorDetail, CreateConnectorInput, ToolIssue } from "../tools/connectors.service.js";
+import { ConnectorsService } from "../tools/connectors.service.js";
+import { type CatalogVersionFiles, type TemplateDeps } from "./catalog-content.js";
+import { type DefinitionRefs } from "./component-state.js";
 /** What an org fills in for one connector template at install (C30). */
 export interface ConnectorInstallInput {
     name?: string;
@@ -37,7 +43,7 @@ export interface PluginInstallInput {
  * agent template (ref = its agent_templates id; like a skill, `skill_version` records the version
  * an install or upgrade added to an existing template).
  */
-export type ComponentKind = "extension" | "connector" | "skill" | "plugin" | "agent_template";
+export type ComponentKind = "extension" | "connector" | "skill" | "plugin" | "agent_template" | "theme";
 export interface UninstallReport {
     removed: {
         kind: ComponentKind;
@@ -46,9 +52,54 @@ export interface UninstallReport {
     kept: {
         kind: ComponentKind;
         ref: string;
-        reason: "pre_existing" | "used_by_agents" | "used_by_other_install" | "used_by_connectors" | "used_by_plugins";
+        reason: "pre_existing" | "used_by_agents" | "used_by_other_install" | "used_by_connectors" | "used_by_plugins"
+        /** A dependency install still wanted on in the org by its own scope: it stays, standalone. */
+         | "wanted_by_scope"
+        /**
+         * A connector the install created, kept by a scope sync uninstall (the plugin disabled or its
+         * scope narrowed, spec §5 rule 8): it stays as the org's own, with its credentials.
+         */
+         | "org_owned";
     }[];
 }
+/**
+ * What switching a plugin off would do, read without changing anything: its components, the ones the
+ * uninstall rules would keep for a reason visible beforehand (a component that pre-existed, or one an
+ * agent uses), and the agents that use the plugin's skills, connectors or agent templates.
+ */
+export interface UninstallPreview {
+    installId: string;
+    name: string;
+    version: string;
+    components: {
+        kind: ComponentKind;
+        ref: string;
+        created: boolean;
+    }[];
+    kept: UninstallReport["kept"];
+    agents: {
+        id: string;
+        name: string;
+        uses: {
+            kind: ComponentKind;
+            ref: string;
+        }[];
+    }[];
+    /**
+     * The plugin's themes on in the org through it (`follow`) that go off with it (themes spec §6):
+     * whether it is the org's default and how many people picked it. Absent when there are none.
+     */
+    themes?: ThemePreview[];
+}
+/** The confirm hash of an uninstall preview: sha256 over its sorted JSON (the scheme of `diffHash`). */
+export declare function uninstallPreviewHash(p: UninstallPreview): string;
+/** Upserts the org's switch row of an item in the caller's transaction (the org lock is held). */
+export declare function upsertOrgSwitch(db: KernelSchemaDb, orgId: string, itemId: string, enabled: boolean, actor: string | null): Promise<void>;
+/** The kernel (actor null, the scope sync) never installs what needs the org's input. */
+export declare class NeedsOrgInput extends ApiError {
+    readonly plugin: string;
+    constructor(plugin: string);
+}
 /** A plugin install in an org (`GET /orgs/:orgId/plugin-installs`). */
 export interface PluginInstallView {
     id: string;
@@ -74,26 +125,13 @@ export interface PluginInstallView {
         skillVersion: number | null;
         dropped: boolean;
     }[];
-    /** The highest version this install can be upgraded to now, null when none (spec §10). */
-    upgradeAvailable: string | null;
     /**
-     * The plugin's extension on the deployment is not the one of this install's version: the org
-     * should upgrade to the deployment's version ("upgrade pending", Decision 10).
+     * Always null / false since plugin scope phase 2: a platform plugin has one version for the
+     * deployment and the platform update moves every org install (ruling F2); kept for the web until
+     * its upgrade dialog goes.
      */
-    deploymentPending: boolean;
-}
-export interface PluginInstallerDeps {
-    db: KernelDb;
-    storage: StorageService;
-    host: Pick<ExtensionHost, "manifests" | "list">;
-    findConnector: (plugin: string, kind: string) => Connector | undefined;
-    connectors: Pick<ConnectorsService, "create" | "removeIn" | "checkCreateInput" | "prepareTemplateUpdate" | "applyTemplateIn">;
-    skills: Pick<SkillsService, "createVersionFromFiles" | "softDeleteIn" | "revertVersionIn">;
-    orgConfigs: Pick<OrgExtensionConfigs, "put" | "disableIn" | "afterDisable" | "enabledDependents">;
-    requests: Pick<CatalogRequestsService, "resolveByInstall">;
-    /** `catalog.staleInstallMinutes`: an install `installing` for longer can be cleaned up by uninstalling it. */
-    staleInstallMinutes: () => number;
-    log?: Pick<Logger, "warn">;
+    upgradeAvailable: null;
+    deploymentPending: false;
 }
 /** A dependency resolved against the catalog. */
 export interface ResolvedDependency {
@@ -158,6 +196,8 @@ export declare class InstallFailure extends Error {
     dependency: string[], rolledBack: boolean);
     get code(): string;
 }
+/** Merged into an install's or uninstall's audit detail (a write made through the Platform tool). */
+type AuditDetail = Record<string, unknown>;
 export interface UninstallCtx {
     report: UninstallReport;
     /** The installs this uninstall is removing (none of them counts as still using a component). */
@@ -169,16 +209,19 @@ export interface UninstallCtx {
     reason?: string;
     opts: {
         actorTokenId?: string;
+        auditDetail?: AuditDetail;
     };
+    /** Uninstalled by the plugin scope sync: the connectors it created stay as the org's own. */
+    via?: "scope";
 }
 /**
- * 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.
  */
-export declare function resolveDependencies(db: KernelDb | Trx, manifest: PluginManifest): Promise<ResolvedDependency[]>;
+export declare function resolveDependencies(db: KernelSchemaDb, manifest: PluginManifest): Promise<ResolvedDependency[]>;
 /**
  * The input a template needs that the org did not give: a static credential (the org's for an
  * org-owned template; for a personal one the installer's own, stored as their personal credential,
@@ -203,9 +246,11 @@ export declare function under(e: unknown, at: string): unknown;
  *    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
@@ -213,15 +258,36 @@ export declare function under(e: unknown, at: string): unknown;
  * 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.
  */
 export declare class PluginInstaller {
-    private readonly d;
-    constructor(d: PluginInstallerDeps);
-    /** The installer's dependencies (shared with `PluginUpgrader`). */
-    get deps(): PluginInstallerDeps;
+    private readonly kdb;
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    private readonly orgLock;
+    private readonly storage;
+    /** The loaded extensions and connectors of this replica (the extension registry). */
+    private readonly registry;
+    private readonly skills;
+    private readonly orgConfigs;
+    private readonly config;
+    /** Org connectors: installs create, upgrade and remove them. */
+    private readonly connectors;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock: OrgLock, storage: StorageService, 
+    /** The loaded extensions and connectors of this replica (the extension registry). */
+    registry: ExtensionRegistry, skills: SkillsService, orgConfigs: OrgExtensionConfigs, config: KernelConfigService, 
+    /** Org connectors: installs create, upgrade and remove them. */
+    connectors: ConnectorsService, log: KernelLogger, txHost: TransactionHost);
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    private get db();
+    /** `catalog.staleInstallMinutes`: an install `installing` for longer can be cleaned up by uninstalling it. */
+    staleInstallMinutes(): number;
     /**
      * The checks an install runs before it creates anything, without the org's input (for the org
      * catalog to run before a request is created): dependency resolution, the extensions deployed and
@@ -230,8 +296,11 @@ export declare class PluginInstaller {
     preflight(orgId: string, actor: string, itemId: string, version: string): Promise<{
         actions: OrgAction[];
     }>;
-    install(orgId: string, actor: string, itemId: string, version: string, input: PluginInstallInput, opts?: {
+    install(orgId: string, actor: string | null, itemId: string, version: string, input: PluginInstallInput, opts?: {
         actorTokenId?: string;
+        auditDetail?: AuditDetail;
+        switchOn?: boolean;
+        via?: "scope";
     }): Promise<PluginInstallView>;
     /**
      * Refuses a plan whose skills would overwrite a skill of other provenance (spec §9.2, Decision
@@ -240,6 +309,12 @@ export declare class PluginInstaller {
      * and a name two plugins of the same plan both bring (the one installed first is the source).
      */
     private assertNoSkillConflicts;
+    /**
+     * 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.
+     */
+    private assertNoThemeClashes;
     /** The connector checks of templates against what this replica loads right now. */
     templateDeps(): TemplateDeps;
     /**
@@ -248,7 +323,20 @@ export declare class PluginInstaller {
      * an empty input. `at` prefixes validation paths (`dependencies.<name>.` for a dependency);
      * `approvedBy` is the root item for a dependency.
      */
-    plan(orgId: string, actor: string, itemId: string, version: string, input: PluginInstallInput | null, at: string, approvedBy: string | undefined): Promise<InstallPlan>;
+    plan(orgId: string, actor: string | null, itemId: string, version: string, input: PluginInstallInput | null, at: string, approvedBy: string | undefined): Promise<InstallPlan>;
+    /**
+     * 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.
+     */
+    impliedProviders(orgId: string, manifest: PluginManifest, templates: {
+        id: string;
+        file: ConnectorTemplateFile;
+    }[], declared: {
+        name: string;
+    }[]): Promise<ResolvedDependency[]>;
     /**
      * 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
@@ -267,7 +355,7 @@ export declare class PluginInstaller {
      * version outside the dependency's range -> `catalog.dependency_unresolved` (org upgrades arrive in
      * phase A).
      */
-    liveDependency(db: KernelDb | Trx, orgId: string, dep: ResolvedDependency): Promise<string | undefined>;
+    liveDependency(db: KernelSchemaDb, orgId: string, dep: ResolvedDependency): Promise<string | undefined>;
     /**
      * The org's live (not failed) install of a dependency's item; `lock` takes it FOR SHARE (the
      * caller holds the org row lock).
@@ -279,21 +367,43 @@ export declare class PluginInstaller {
      * cannot leave the component pointing at a removed install. `created` false: the org's existing
      * install, if any (returns its id, undefined when there is none); it must be `installed`
      * (`installing` -> 409 `plugin.install_in_progress`, retry later) and in range. `created` true:
-     * `child`, the dependency install this install just created, must still exist.
+     * `child`, the dependency install this install just created, must still exist. A step of an
+     * install or upgrade: it commits on its own (`requires_new`), the undo on failure relies on it.
      */
-    recordDependency(orgId: string, dep: ResolvedDependency, record: (c: Component, t: Trx) => Promise<void>, child?: string): Promise<string | undefined>;
+    recordDependency(orgId: string, dep: ResolvedDependency, record: (c: Component) => Promise<void>, child?: string): Promise<string | undefined>;
     /**
      * Runs a plan: the install row, then the steps (see the class comment). Throws
      * {@link InstallFailure} once the row exists (after rolling back); errors before it propagate
      * as they are. Returns the install id.
      */
-    execute(orgId: string, actor: string, plan: InstallPlan, opts: {
+    execute(orgId: string, actor: string | null, plan: InstallPlan, opts: {
         actorTokenId?: string;
+        auditDetail?: AuditDetail;
     }, ctx: {
         actions: OrgAction[];
         approvedBy?: string;
         parent?: string;
+        switchOn?: boolean;
+        /** Installed by the plugin scope sync (recorded in the audits). */
+        via?: "scope";
     }): Promise<string>;
+    /**
+     * The install row (role and item policy re-checked under the lock; one live install per org and
+     * item). A step of the install: committed on its own.
+     */
+    /**
+     * Enables a plugin's extension for the org and records it as a component of the install, in one
+     * transaction (`put` joins it): "enabled before" is decided under the org row lock (already
+     * enabled: `put` writes nothing, the config is untouched, the component is recorded as not
+     * created), and the ledger row is written before the COMMIT, so no concurrent uninstall fits
+     * between enabling and recording. Used by the install and the upgrade.
+     */
+    enableExtension(orgId: string, name: string, input: OrgExtensionInput, actor: string | null, actorTokenId: string | undefined, opts: Pick<OrgExtensionPutOptions, "viaItem" | "approvedBy">, record: (c: Component) => Promise<void>): Promise<void>;
+    private createInstallRow;
+    /** The install `installed` and its `plugin.org_installed` audit, under the org row lock (its own transaction). */
+    private markInstalled;
+    /** The install `failed` with `{ step, code }` and its `plugin.org_install_failed` audit (its own transaction). */
+    private markFailed;
     /**
      * The extension to enable: the plugin's own, when it has one. Not loaded on this replica ->
      * `catalog.not_deployed`; not yet enabled in this org while its own catalog item is disabled ->
@@ -311,8 +421,14 @@ export declare class PluginInstaller {
      * an org admin re-enabled by hand or a skill version a user uploaded since.
      */
     private rollback;
+    /**
+     * Undoes one component of a failed install and deletes its component row, under the org row lock,
+     * in a transaction of its own (committed when it returns); returns the extensions it disabled
+     * (the caller notifies them).
+     */
+    private rollbackOne;
     /** Removes one component (one already gone is no error); returns whether anything changed. */
-    removeComponent(t: Trx, orgId: string, actor: string, c: Component, reason: string): Promise<boolean>;
+    removeComponent(orgId: string, actor: string | null, c: Component, reason: string): Promise<boolean>;
     /**
      * Uninstall (the plugin's component actions, see `requiredActions`, re-checked under the org row
      * lock, one transaction). Removes only components with created=true:
@@ -335,23 +451,41 @@ export declare 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`.
      */
-    uninstall(orgId: string, actor: string, installId: string, opts?: {
+    uninstall(orgId: string, actor: string | null, installId: string, opts?: {
         actorTokenId?: string;
+        auditDetail?: AuditDetail;
+        via?: "scope";
+    }, sw?: {
+        expectHash?: string;
     }): Promise<UninstallReport>;
+    /**
+     * 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`).
+     */
+    private writeUninstall;
+    /**
+     * 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).
+     */
+    assertKeepsPlatformDefault(orgId: string, installId: string): Promise<void>;
     /**
      * The oldest other live install (not in `removing`) that has component `kind` / `ref`, or
      * undefined.
      */
-    heir(t: Trx, orgId: string, removing: Set<string>, kind: ComponentKind, ref: string): Promise<string | undefined>;
+    heir(orgId: string, removing: Set<string>, kind: ComponentKind, ref: string): Promise<string | undefined>;
     /** Passes ownership of a component to `heir` (its component row becomes created=true). */
-    handOver(t: Trx, heir: string, kind: ComponentKind, ref: string): Promise<void>;
+    handOver(heir: string, kind: ComponentKind, ref: string): Promise<void>;
     /**
      * Uninstalls one install in the caller's transaction (see {@link uninstall}); dependency installs
      * it created recurse. Its own components' outcomes go into `ctx.report` (and its audit); the
      * outcome of the install itself is returned for the caller to report: `missing`, `kept` (another
      * install outside this uninstall depends on it) or `removed`.
      */
-    uninstallIn(t: Trx, orgId: string, actor: string, installId: string, ctx: UninstallCtx): Promise<"missing" | "kept" | "removed">;
+    uninstallIn(orgId: string, actor: string | null, installId: string, ctx: UninstallCtx): Promise<"missing" | "kept" | "removed" | "wanted_by_scope">;
     /**
      * The uninstall rules for one component an install created (a skill, connector or extension;
      * dependency installs recurse through {@link uninstallIn}), in the caller's transaction: kept
@@ -362,7 +496,7 @@ export declare class PluginInstaller {
      * (`used_by_plugins`); otherwise removed (`removed`, or `gone` when it no longer existed). Used
      * by uninstall and by an upgrade's removals.
      */
-    decideRemovalIn(t: Trx, orgId: string, actor: string, c: Component, removing: Set<string>, agentRefs: {
+    decideRemovalIn(orgId: string, actor: string | null, c: Component, removing: Set<string>, agentRefs: {
         connectors: Set<string>;
         skills: Set<string>;
         templates: Set<string>;
@@ -380,21 +514,92 @@ export declare class PluginInstaller {
      * extension among them needs `afterDisable` once committed). Used when an upgrade fails and when
      * an interrupted one is cleaned up.
      */
-    undoUpgradeIn(t: Trx, orgId: string, actor: string, installId: string, steps: readonly UpgradeStep[], reason: string): Promise<{
+    undoUpgradeIn(orgId: string, actor: string | null, installId: string, steps: readonly UpgradeStep[], reason: string): Promise<{
         kind: ComponentKind;
         ref: string;
     }[]>;
+    /**
+     * 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).
+     */
+    addMissingDependencies(orgId: string, installId: string): Promise<string[]>;
+    /**
+     * 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.
+     */
+    missingConnectors(orgId: string, itemId: string): Promise<{
+        installId: string;
+        version: string;
+        templates: {
+            id: string;
+            file: ConnectorTemplateFile;
+        }[];
+    } | undefined>;
+    /**
+     * 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.
+     */
+    configureConnectors(orgId: string, actor: string, itemId: string, input: PluginInstallInput, opts?: {
+        actorTokenId?: string;
+    }): Promise<{
+        templateId: string;
+        connectorId: string;
+    }[]>;
+    /** A configured connector's ledger row (its own transaction). */
+    private recordConnector;
+    /**
+     * 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>`.
+     */
+    addTemplateConnector(orgId: string, actor: string, templateId: string, input: {
+        name?: string | undefined;
+        config: Omit<ConnectorInstallInput, "name">;
+    }, opts?: {
+        actorTokenId?: string;
+    }): Promise<{
+        connector: ConnectorDetail;
+        issues: ToolIssue[];
+    }>;
+    /**
+     * 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).
+     */
+    private recordOnLiveInstall;
     /** The connector kinds an extension provides (the `connector@1` implementations loaded on this replica). */
     connectorKindsOf(plugin: string): 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).
      */
-    agentRefs(t: Trx, orgId: string): Promise<{
-        connectors: Set<string>;
-        skills: Set<string>;
-        templates: Set<string>;
-    }>;
+    previewUninstall(orgId: string, installId: string): Promise<UninstallPreview>;
+    /**
+     * 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.
+     */
+    agentRefs(orgId: string): Promise<DefinitionRefs>;
 }
 /**
  * The skill names of a catalog version, read from each skill's SKILL.md in storage (the names are
@@ -415,7 +620,7 @@ export interface SkillPlan {
  * The skill conflicts of a plan, depth first in install order (dependencies before the plugin).
  * Exported for the upgrade preview.
  */
-export declare function planSkillConflicts(db: KernelDb | Trx, orgId: string, plan: SkillPlan): Promise<SkillConflict[]>;
+export declare function planSkillConflicts(db: KernelSchemaDb, orgId: string, plan: SkillPlan): Promise<SkillConflict[]>;
 /**
  * One step a running upgrade took, journaled in `plugin_installs.upgrade.done` (migration 0049) so
  * a failed or interrupted upgrade can be undone: `created` a component the upgrade created (its