@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,447 @@
+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 { 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>;
+/** What an org fills in for one connector template at install (C30). */
+export interface ConnectorInstallInput {
+    name?: string;
+    slug?: string;
+    /** Only the paths the template lists in `editableEndpoint`. */
+    endpoint?: Record<string, unknown>;
+    credential?: Record<string, unknown>;
+    client?: {
+        clientId: string;
+        clientSecret?: string;
+    };
+}
+/**
+ * What an org fills in when installing a plugin (the body of `POST …/catalog/:itemId/install`
+ * without `version`). Dependencies get no input: one whose templates need credentials is installed
+ * on its own first.
+ */
+export interface PluginInstallInput {
+    connectors?: Record<string, ConnectorInstallInput>;
+    /** The org config of the plugin's extension (used only when this install enables it). */
+    extensionConfig?: Record<string, unknown>;
+}
+/**
+ * `plugin` is a dependency install (ref = its plugin install id); `agent_template` (phase C) an
+ * 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 interface UninstallReport {
+    removed: {
+        kind: ComponentKind;
+        ref: string;
+    }[];
+    kept: {
+        kind: ComponentKind;
+        ref: string;
+        reason: "pre_existing" | "used_by_agents" | "used_by_other_install" | "used_by_connectors" | "used_by_plugins";
+    }[];
+}
+/** A plugin install in an org (`GET /orgs/:orgId/plugin-installs`). */
+export interface PluginInstallView {
+    id: string;
+    itemId: string;
+    name: string;
+    version: string;
+    status: "installing" | "installed" | "failed" | "uninstalling" | "upgrading";
+    installedBy: string | null;
+    installedAt: string;
+    /** The failed install's step and code, or the last failed upgrade's (the install stays installed). */
+    error: {
+        step: string;
+        code: string;
+    } | null;
+    /**
+     * `dropped`: an upgrade removed it from the plugin but kept it because an agent uses it ("no
+     * longer in the plugin"); uninstalling still removes it once nothing uses it.
+     */
+    components: {
+        kind: ComponentKind;
+        ref: string;
+        created: boolean;
+        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).
+     */
+    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">;
+}
+/** A dependency resolved against the catalog. */
+export interface ResolvedDependency {
+    name: string;
+    range: string;
+    itemId: string;
+    version: string;
+}
+/** How deep plugin dependencies may nest (the root plugin's dependencies are level 1). */
+export declare const DEPENDENCY_DEPTH_LIMIT = 10;
+/** A component as an install records it (see `plugin_install_components`). */
+export interface Component {
+    kind: ComponentKind;
+    ref: string;
+    created: boolean;
+    /** A skill's or agent template's version this install added to an existing one. */
+    skillVersion: number | null;
+    /** A connector's template id (written to `template_id`, migration 0049). */
+    templateId?: string;
+}
+export type Step = "dependencies" | "extension" | "connectors" | "skills" | "agent_templates";
+/** What one plugin install will do, checked before anything is written. */
+export interface InstallPlan {
+    itemId: string;
+    name: string;
+    version: string;
+    manifest: PluginManifest;
+    row: CatalogVersionFiles;
+    /** The version's source format, recorded on the org skill versions it creates. */
+    sourceFormat: SourceFormat;
+    /** The plugin's own extension, to enable in the org. */
+    extension: string | null;
+    extensionConfig: Record<string, unknown> | undefined;
+    templates: {
+        id: string;
+        file: ConnectorTemplateFile;
+    }[];
+    /** The connector inputs built from the templates (empty for a preflight without input). */
+    connectors: Map<string, CreateConnectorInput>;
+    /** The names of the plugin's skills (from each SKILL.md). */
+    skillNames: string[];
+    /** The plugin's agent templates (phase C). */
+    agentTemplates: {
+        path: string;
+        template: AgentTemplate;
+    }[];
+    /** `plan` null: the dependency was already installed in the org when planned. */
+    dependencies: {
+        dep: ResolvedDependency;
+        plan: InstallPlan | null;
+    }[];
+}
+/** A failed install step, carried up through the dependency installs to the root install. */
+export declare class InstallFailure extends Error {
+    readonly step: Step;
+    readonly cause: unknown;
+    /** The dependency path when a dependency failed (outermost first). */
+    readonly dependency: string[];
+    readonly rolledBack: boolean;
+    constructor(step: Step, cause: unknown, 
+    /** The dependency path when a dependency failed (outermost first). */
+    dependency: string[], rolledBack: boolean);
+    get code(): string;
+}
+export interface UninstallCtx {
+    report: UninstallReport;
+    /** The installs this uninstall is removing (none of them counts as still using a component). */
+    removing: Set<string>;
+    /** The install whose `plugin` component led here (a dependency uninstall). */
+    from?: string;
+    /** Re-check the actor's org actions (false for a rollback). */
+    authorize: boolean;
+    reason?: string;
+    opts: {
+        actorTokenId?: string;
+    };
+}
+/**
+ * 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 ->
+ * `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[]>;
+/**
+ * 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,
+ * since creating the connector lists its tools with it), or the OAuth client of a
+ * client-credentials / manual-client template. Undefined when nothing is missing.
+ * `personalCredential: false` keeps a personal static template optional (an existing connector
+ * whose template's auth changed: its members keep giving their own).
+ */
+export declare function missingTemplateInput(template: ConnectorTemplateSpec, given: ConnectorInstallInput | undefined, o?: {
+    personalCredential?: boolean;
+}): "credential" | "client" | undefined;
+/** `e` with its validation paths under `at` (input errors of a template's connector). */
+export declare function under(e: unknown, at: string): unknown;
+/**
+ * Org install and uninstall of plugins (spec §10, C31). Before anything is written the install is
+ * planned for the whole dependency tree ({@link resolveDependencies}; the extension deployed, the
+ * template input valid, else a 4xx). Install, in order, per plugin:
+ * 1. dependencies, depth first: each one not yet installed in the org gets its own nested
+ *    `plugin_installs` row, recorded as a `plugin` component of the parent (created=true); one
+ *    already installed is recorded created=false;
+ * 2. the plugin's extension, enabled in the org (`catalog.not_deployed` when the deployment does
+ *    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).
+ * 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
+ * this install created (nested dependency installs included) are undone in reverse order, the
+ * 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).
+ */
+export declare class PluginInstaller {
+    private readonly d;
+    constructor(d: PluginInstallerDeps);
+    /** The installer's dependencies (shared with `PluginUpgrader`). */
+    get deps(): PluginInstallerDeps;
+    /**
+     * 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
+     * the template connectors available. Returns the org actions the whole install needs.
+     */
+    preflight(orgId: string, actor: string, itemId: string, version: string): Promise<{
+        actions: OrgAction[];
+    }>;
+    install(orgId: string, actor: string, itemId: string, version: string, input: PluginInstallInput, opts?: {
+        actorTokenId?: string;
+    }): Promise<PluginInstallView>;
+    /**
+     * Refuses a plan whose skills would overwrite a skill of other provenance (spec §9.2, Decision
+     * 8) with 409 `plugin.skill_conflict`, before anything is written: for the plugin and each
+     * dependency it installs, an org skill of the same name that is the org's own or another item's,
+     * and a name two plugins of the same plan both bring (the one installed first is the source).
+     */
+    private assertNoSkillConflicts;
+    /** The connector checks of templates against what this replica loads right now. */
+    templateDeps(): TemplateDeps;
+    /**
+     * Plans the install of one plugin version and, depth first, of its dependencies not yet
+     * installed in the org. `input` null skips the input checks (preflight); dependencies always get
+     * 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>;
+    /**
+     * 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
+     * needs given (else 400; a dependency's says to install it on its own first).
+     */
+    planConnector(actor: string, plugin: {
+        itemId: string;
+        version: string;
+        name: string;
+    }, ct: {
+        id: string;
+        file: ConnectorTemplateFile;
+    }, input: PluginInstallInput, at: string, approvedBy: string | undefined): CreateConnectorInput;
+    /**
+     * The org's live install of a dependency's item (installing or installed), or undefined. One at a
+     * 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>;
+    /**
+     * The org's live (not failed) install of a dependency's item; `lock` takes it FOR SHARE (the
+     * caller holds the org row lock).
+     */
+    private findLiveDependency;
+    /**
+     * Records an install of `dep` as a `plugin` component of the install, checked and written in one
+     * transaction under the org row lock, so a concurrent uninstall or a sibling install's rollback
+     * 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.
+     */
+    recordDependency(orgId: string, dep: ResolvedDependency, record: (c: Component, t: Trx) => 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: {
+        actorTokenId?: string;
+    }, ctx: {
+        actions: OrgAction[];
+        approvedBy?: string;
+        parent?: string;
+    }): Promise<string>;
+    /**
+     * 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 ->
+     * `catalog.item_disabled` (a disabled item is a master switch, Ruling M-5); already enabled is
+     * unaffected.
+     */
+    planExtension(orgId: string, manifest: PluginManifest): Promise<string | null>;
+    /** The input only names the plugin's template ids, and an extension config needs an extension. */
+    private checkInput;
+    /**
+     * Undoes the components this install created, in reverse order (the role is not re-checked: it
+     * undoes this install's own changes); returns the ones that failed. The component rows of undone
+     * (or already gone) components are deleted in the same transaction, so cleaning up the failed
+     * install later only handles what failed to undo or was kept, and does not undo again an extension
+     * an org admin re-enabled by hand or a skill version a user uploaded since.
+     */
+    private rollback;
+    /** 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>;
+    /**
+     * Uninstall (the plugin's component actions, see `requiredActions`, re-checked under the org row
+     * lock, one transaction). Removes only components with created=true:
+     * - a skill is kept when an agent selects it (used_by_agents) or another plugin install in this
+     *   org uses it too (used_by_other_install);
+     * - a connector is kept when an agent references it (used_by_agents);
+     * - an extension is kept when another plugin install uses it too (used_by_other_install), a
+     *   connector still uses a connector it provides (used_by_connectors), or another enabled
+     *   extension depends on it (used_by_plugins);
+     * - a dependency install (`plugin`) is uninstalled by these same rules, after the plugin's own
+     *   components; it is kept when another install outside this uninstall depends on it
+     *   (used_by_other_install);
+     * - components that existed before are kept (pre_existing).
+     * When kept for used_by_other_install, ownership passes to the oldest remaining install (its
+     * component row becomes created=true), so the uninstall order doesn't change the end result.
+     * Uninstalling a dependency another install still uses removes nothing and reports it kept
+     * (`plugin`, used_by_other_install). Deletes the install rows and audits `plugin.org_uninstalled`
+     * per install (detail has removed / kept). Can be uninstalled: installed; failed (already rolled
+     * back: clears the row and leftovers); installing for longer than `catalog.staleInstallMinutes`
+     * (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?: {
+        actorTokenId?: string;
+    }): Promise<UninstallReport>;
+    /**
+     * 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>;
+    /** Passes ownership of a component to `heir` (its component row becomes created=true). */
+    handOver(t: Trx, 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">;
+    /**
+     * 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
+     * when an agent uses the skill / connector (`used_by_agents`), when another live install outside
+     * `removing` has it (`used_by_other_install`, ownership handed over to the oldest one, so the
+     * uninstall order doesn't change the result), when a connector still uses the extension's
+     * connector kind (`used_by_connectors`) or another enabled extension depends on it
+     * (`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: {
+        connectors: Set<string>;
+        skills: Set<string>;
+        templates: Set<string>;
+    }, reason: string): Promise<"removed" | "gone" | UninstallReport["kept"][number]["reason"]>;
+    /** The order extensions are uninstalled in: the reverse of the install (requires) order; extensions not loaded on this replica last. */
+    private uninstallExtensionOrder;
+    /** The org's plugin installs (failed ones included), newest first; `installId` picks one. */
+    list(orgId: string, installId?: string): Promise<PluginInstallView[]>;
+    /**
+     * Undoes the steps of an upgrade in the caller's transaction (the caller holds the org row lock),
+     * in reverse order: components it created are removed (a dependency install by the uninstall
+     * rules, an extension another enabled extension depends on is kept), the ledger rows it added
+     * are deleted, and versions it added to skills are reverted (`revertVersionIn` reverts exactly
+     * one version, and an upgrade adds at most one per skill). Returns the components removed (an
+     * 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<{
+        kind: ComponentKind;
+        ref: string;
+    }[]>;
+    /** 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.
+     */
+    agentRefs(t: Trx, orgId: string): Promise<{
+        connectors: Set<string>;
+        skills: Set<string>;
+        templates: Set<string>;
+    }>;
+}
+/**
+ * The skill names of a catalog version, read from each skill's SKILL.md in storage (the names are
+ * not in plugin.json). Used by install planning and the upgrade preview.
+ */
+export declare function catalogSkillNames(storage: StorageService, row: CatalogVersionFiles, manifest: PluginManifest): Promise<string[]>;
+/** The parts of an {@link InstallPlan} the skill conflict check reads (an upgrade builds one too). */
+export interface SkillPlan {
+    itemId: string;
+    name: string;
+    version: string;
+    skillNames: string[];
+    dependencies: {
+        plan: SkillPlan | null;
+    }[];
+}
+/**
+ * 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[]>;
+/**
+ * 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
+ * ledger row created=true), `recorded` an existing component it added to the ledger
+ * (created=false), `skill_version` / `template_version` a version it added to a skill / an agent
+ * template.
+ */
+export type UpgradeStep = {
+    op: "created";
+    kind: ComponentKind;
+    ref: string;
+} | {
+    op: "recorded";
+    kind: ComponentKind;
+    ref: string;
+} | {
+    op: "skill_version";
+    ref: string;
+    version: number;
+} | {
+    op: "template_version";
+    ref: string;
+    version: number;
+};
+/** The journaled steps of `plugin_installs.upgrade` (malformed entries are skipped). */
+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 {};