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

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

@@ -1,5 +1,6 @@
 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";
@@ -10,10 +11,11 @@ import { OrgLock } from "../orgs/org-lock.js";
 import type { OrgAction } from "../orgs/roles.js";
 import { type SkillConflict, SkillsService } from "../skills/skills.service.js";
 import { StorageService } from "../storage/storage.service.js";
-import type { CreateConnectorInput } from "../tools/connectors.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 { CatalogRequestsService } from "./requests.service.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;
@@ -41,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;
@@ -50,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;
@@ -78,13 +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;
+    upgradeAvailable: null;
+    deploymentPending: false;
 }
 /** A dependency resolved against the catalog. */
 export interface ResolvedDependency {
@@ -149,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). */
@@ -160,12 +209,15 @@ 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.
  */
@@ -194,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
@@ -204,9 +258,10 @@ 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 kdb;
@@ -217,7 +272,6 @@ export declare class PluginInstaller {
     private readonly registry;
     private readonly skills;
     private readonly orgConfigs;
-    private readonly requests;
     private readonly config;
     /** Org connectors: installs create, upgrade and remove them. */
     private readonly connectors;
@@ -227,7 +281,7 @@ export declare class PluginInstaller {
     /** 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, requests: CatalogRequestsService, config: KernelConfigService, 
+    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). */
@@ -242,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
@@ -252,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;
     /**
@@ -260,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
@@ -300,12 +376,16 @@ export declare class PluginInstaller {
      * {@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
@@ -318,13 +398,8 @@ export declare class PluginInstaller {
      * 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, actorTokenId: string | undefined, opts: Pick<OrgExtensionPutOptions, "viaItem" | "approvedBy">, record: (c: Component) => Promise<void>): Promise<void>;
+    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;
-    /**
-     * 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.
-     */
-    private installAgentTemplate;
     /** 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). */
@@ -353,7 +428,7 @@ export declare class PluginInstaller {
      */
     private rollbackOne;
     /** Removes one component (one already gone is no error); returns whether anything changed. */
-    removeComponent(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:
@@ -376,11 +451,27 @@ 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. */
+    /**
+     * 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.
@@ -394,7 +485,7 @@ export declare class PluginInstaller {
      * 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(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
@@ -405,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(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>;
@@ -423,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(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(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
@@ -487,3 +649,4 @@ export type UpgradeStep = {
 export declare function journalEntries(upgrade: unknown): UpgradeStep[];
 /** The org actions a plan needs: the union over the plugins it installs (spec §10). */
 export declare function planActions(plan: InstallPlan): OrgAction[];
+export {};