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

package/dist/catalog/org-catalog.controller.d.ts

@@ -0,0 +1,128 @@
+import type { FastifyReply } from "fastify";
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { CatalogIcon, OrgCatalogDetail, OrgCatalogItem, OrgCatalogService, OrgInstallResult, OrgUpgradeResult } from "./org-catalog.service.js";
+import type { PluginInstaller, PluginInstallView, UninstallReport } from "./plugin-install.js";
+import type { UpgradePreview } from "./plugin-upgrade.js";
+import type { CatalogRequestsService, CatalogRequestView } from "./requests.service.js";
+declare const RequestBody: z.ZodObject<{
+    note: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** The org install body: the version (default the latest), template input, the extension's org config. */
+declare const InstallBody: z.ZodObject<{
+    version: z.ZodOptional<z.ZodString>;
+    connectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        client: z.ZodOptional<z.ZodObject<{
+            clientId: z.ZodString;
+            clientSecret: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    extensionConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/** The upgrade preview body: the target version. */
+declare const UpgradePreviewBody: z.ZodObject<{
+    version: z.ZodString;
+}, z.core.$strict>;
+/** The upgrade body: the target version, the preview's diffHash, the inputs it listed. */
+declare const UpgradeBody: z.ZodObject<{
+    version: z.ZodString;
+    diffHash: z.ZodString;
+    connectors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        client: z.ZodOptional<z.ZodObject<{
+            clientId: z.ZodString;
+            clientSecret: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    extensionConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * 条目图标的响应头：图标可能是 SVG（可含脚本），只许网页以 `<img>` 显示；直接打开时 CSP sandbox 禁止脚本与一切外部
+ * 请求，nosniff 防浏览器按内容另行判型。
+ */
+export declare function sendCatalogIcon(reply: FastifyReply, icon: CatalogIcon): Promise<void>;
+declare const DecideBody: z.ZodObject<{
+    decision: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+    }>;
+}, z.core.$strict>;
+declare const AdminListQuery: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        approved: "approved";
+        cancelled: "cancelled";
+        pending: "pending";
+        rejected: "rejected";
+    }>>;
+}, z.core.$strip>;
+/**
+ * The enterprise catalog from an organization's view (`/api/v1/orgs/:orgId/...`, human users only):
+ * - `GET catalog` (`catalog.read`, member and up; members do not see disabled items);
+ * - `POST catalog/:itemId/requests` (`catalog.request`): a member request, into the org admins'
+ *   inbox;
+ * - `POST catalog/:itemId/install`: the route only requires `catalog.read`; the service re-checks
+ *   the plugin's component actions (`org.extensions.manage` for an extension, `connectors.manage`
+ *   for templates, `skills.manage` for skills) inside the org row lock; needs_approval without a
+ *   grant -> 202 `{ request }`, otherwise 201 `{ installed, install }` (the install view);
+ * - `GET / DELETE plugin-installs[/:installId]` (`org.extensions.manage`; uninstall re-checks the
+ *   plugin's component actions in the service);
+ * - `POST plugin-installs/:installId/upgrade/preview` and `.../upgrade` (spec §10; the route only
+ *   requires `catalog.read`, the service re-checks the component actions of both versions):
+ *   preview -> 200 `{ from, to, diffHash, components, inputs, templates }`; upgrade -> 200 `{ install }`, or
+ *   202 `{ request }` for a needs_approval item without a grant;
+ * - `POST catalog-requests/:id/decide` (`catalog.decide`, org admins).
+ */
+export declare class OrgCatalogController {
+    private readonly catalog;
+    private readonly requests;
+    private readonly pluginInstaller;
+    constructor(catalog: OrgCatalogService, requests: CatalogRequestsService, pluginInstaller: PluginInstaller);
+    list(principal: Principal, org: OrgContext): Promise<{
+        items: OrgCatalogItem[];
+    }>;
+    /**
+     * Item detail and what the install wizard needs (members do not see disabled items -> 404
+     * `catalog.item_not_found`).
+     */
+    detail(principal: Principal, org: OrgContext, itemId: string): Promise<OrgCatalogDetail>;
+    /**
+     * The item's icon (connector templates / plugins; svg or png), see {@link sendCatalogIcon}. No icon
+     * -> 404 `catalog.icon_not_found`; members do not see disabled items.
+     */
+    icon(org: OrgContext, itemId: string, reply: FastifyReply): Promise<void>;
+    request(principal: Principal, org: OrgContext, itemId: string, body: z.infer<typeof RequestBody>): Promise<{
+        request: CatalogRequestView;
+        created: boolean;
+    }>;
+    install(principal: Principal, org: OrgContext, itemId: string, body: z.infer<typeof InstallBody>, reply: FastifyReply): Promise<Omit<OrgInstallResult, "status">>;
+    listInstalls(org: OrgContext): Promise<{
+        installs: PluginInstallView[];
+    }>;
+    uninstall(principal: Principal, org: OrgContext, installId: string): Promise<UninstallReport>;
+    upgradePreview(principal: Principal, org: OrgContext, installId: string, body: z.infer<typeof UpgradePreviewBody>): Promise<UpgradePreview>;
+    upgrade(principal: Principal, org: OrgContext, installId: string, body: z.infer<typeof UpgradeBody>, reply: FastifyReply): Promise<Omit<OrgUpgradeResult, "status">>;
+    decide(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof DecideBody>): Promise<{
+        request: CatalogRequestView;
+    }>;
+}
+/** Enterprise admins decide deployment-level catalog requests (`/api/v1/admin/catalog/requests`). */
+export declare class AdminCatalogRequestsController {
+    private readonly requests;
+    constructor(requests: CatalogRequestsService);
+    list(q: z.infer<typeof AdminListQuery>): Promise<{
+        requests: CatalogRequestView[];
+    }>;
+    decide(principal: Principal, id: string, body: z.infer<typeof DecideBody>): Promise<{
+        request: CatalogRequestView;
+    }>;
+}
+export {};

package/dist/catalog/org-catalog.controller.js

@@ -0,0 +1,277 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Query, Res, } from "@nestjs/common";
+import { z } from "zod";
+import { CATALOG_REQUESTS, ORG_CATALOG, PLUGIN_INSTALLER } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { roleAtLeast } from "../orgs/roles.js";
+import { CredentialValue } from "../tools/connectors.controller.js";
+const RequestBody = z
+    .object({
+    note: z.string().max(1000).optional(),
+    version: z.string().min(1).max(256).optional(),
+})
+    .strict();
+const ConnectorInput = z
+    .object({
+    name: z.string().trim().min(1).max(80).optional(),
+    slug: z.string().max(24).optional(),
+    endpoint: z.record(z.string(), z.unknown()).optional(),
+    credential: CredentialValue.optional(),
+    client: z
+        .object({
+        clientId: z.string().min(1).max(500),
+        clientSecret: z.string().min(1).max(4000).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+/** The org install body: the version (default the latest), template input, the extension's org config. */
+const InstallBody = z
+    .object({
+    version: z.string().min(1).max(256).optional(),
+    connectors: z.record(z.string(), ConnectorInput).optional(),
+    extensionConfig: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+/** The upgrade preview body: the target version. */
+const UpgradePreviewBody = z.object({ version: z.string().min(1).max(256) }).strict();
+/** The upgrade body: the target version, the preview's diffHash, the inputs it listed. */
+const UpgradeBody = z
+    .object({
+    version: z.string().min(1).max(256),
+    diffHash: z.string().regex(/^[0-9a-f]{64}$/),
+    connectors: z.record(z.string(), ConnectorInput).optional(),
+    extensionConfig: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+/**
+ * 条目图标的响应头：图标可能是 SVG（可含脚本），只许网页以 `<img>` 显示；直接打开时 CSP sandbox 禁止脚本与一切外部
+ * 请求，nosniff 防浏览器按内容另行判型。
+ */
+export async function sendCatalogIcon(reply, icon) {
+    await reply
+        .header("content-type", icon.contentType)
+        .header("x-content-type-options", "nosniff")
+        .header("content-security-policy", "sandbox; default-src 'none'; style-src 'unsafe-inline'")
+        .header("cache-control", "private, max-age=300")
+        .send(Buffer.from(icon.data.buffer, icon.data.byteOffset, icon.data.byteLength));
+}
+const DecideBody = z.object({ decision: z.enum(["approve", "reject"]) }).strict();
+const AdminListQuery = z.object({
+    status: z.enum(["pending", "approved", "rejected", "cancelled"]).optional(),
+});
+/**
+ * The enterprise catalog from an organization's view (`/api/v1/orgs/:orgId/...`, human users only):
+ * - `GET catalog` (`catalog.read`, member and up; members do not see disabled items);
+ * - `POST catalog/:itemId/requests` (`catalog.request`): a member request, into the org admins'
+ *   inbox;
+ * - `POST catalog/:itemId/install`: the route only requires `catalog.read`; the service re-checks
+ *   the plugin's component actions (`org.extensions.manage` for an extension, `connectors.manage`
+ *   for templates, `skills.manage` for skills) inside the org row lock; needs_approval without a
+ *   grant -> 202 `{ request }`, otherwise 201 `{ installed, install }` (the install view);
+ * - `GET / DELETE plugin-installs[/:installId]` (`org.extensions.manage`; uninstall re-checks the
+ *   plugin's component actions in the service);
+ * - `POST plugin-installs/:installId/upgrade/preview` and `.../upgrade` (spec §10; the route only
+ *   requires `catalog.read`, the service re-checks the component actions of both versions):
+ *   preview -> 200 `{ from, to, diffHash, components, inputs, templates }`; upgrade -> 200 `{ install }`, or
+ *   202 `{ request }` for a needs_approval item without a grant;
+ * - `POST catalog-requests/:id/decide` (`catalog.decide`, org admins).
+ */
+let OrgCatalogController = class OrgCatalogController {
+    catalog;
+    requests;
+    pluginInstaller;
+    constructor(catalog, requests, pluginInstaller) {
+        this.catalog = catalog;
+        this.requests = requests;
+        this.pluginInstaller = pluginInstaller;
+    }
+    async list(principal, org) {
+        const p = requireUser(principal);
+        return { items: await this.catalog.list(org.orgId, p.account.id) };
+    }
+    /**
+     * Item detail and what the install wizard needs (members do not see disabled items -> 404
+     * `catalog.item_not_found`).
+     */
+    detail(principal, org, itemId) {
+        const p = requireUser(principal);
+        return this.catalog.detail(org.orgId, p.account.id, itemId);
+    }
+    /**
+     * The item's icon (connector templates / plugins; svg or png), see {@link sendCatalogIcon}. No icon
+     * -> 404 `catalog.icon_not_found`; members do not see disabled items.
+     */
+    async icon(org, itemId, reply) {
+        const icon = await this.catalog.icon(itemId, roleAtLeast(org.role, "admin"));
+        await sendCatalogIcon(reply, icon);
+    }
+    async request(principal, org, itemId, body) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        return this.requests.request(org.orgId, p.account.id, itemId, body, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+    }
+    async install(principal, org, itemId, body, reply) {
+        const p = requireUser(principal);
+        const r = await this.catalog.install(org.orgId, p.account.id, itemId, body, patTokenId(p));
+        reply.status(r.status);
+        const { status: _status, ...rest } = r;
+        return rest;
+    }
+    async listInstalls(org) {
+        return { installs: await this.pluginInstaller.list(org.orgId) };
+    }
+    async uninstall(principal, org, installId) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        return this.pluginInstaller.uninstall(org.orgId, p.account.id, installId, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+    }
+    upgradePreview(principal, org, installId, body) {
+        const p = requireUser(principal);
+        return this.catalog.upgradePreview(org.orgId, p.account.id, installId, body.version);
+    }
+    async upgrade(principal, org, installId, body, reply) {
+        const p = requireUser(principal);
+        const r = await this.catalog.upgrade(org.orgId, p.account.id, installId, body, patTokenId(p));
+        reply.status(r.status);
+        const { status: _status, ...rest } = r;
+        return rest;
+    }
+    async decide(principal, org, id, body) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        return {
+            request: await this.requests.decideOrg(org.orgId, p.account.id, id, body.decision, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
+        };
+    }
+};
+__decorate([
+    Get("catalog"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], OrgCatalogController.prototype, "list", null);
+__decorate([
+    Get("catalog/:itemId"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("itemId"))
+], OrgCatalogController.prototype, "detail", null);
+__decorate([
+    Get("catalog/:itemId/icon"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentOrg()),
+    __param(1, Param("itemId")),
+    __param(2, Res())
+], OrgCatalogController.prototype, "icon", null);
+__decorate([
+    Post("catalog/:itemId/requests"),
+    OrgAction("catalog.request"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("itemId")),
+    __param(3, Body(new ZodPipe(RequestBody)))
+], OrgCatalogController.prototype, "request", null);
+__decorate([
+    Post("catalog/:itemId/install"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("itemId")),
+    __param(3, Body(new ZodPipe(InstallBody))),
+    __param(4, Res({ passthrough: true }))
+], OrgCatalogController.prototype, "install", null);
+__decorate([
+    Get("plugin-installs"),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentOrg())
+], OrgCatalogController.prototype, "listInstalls", null);
+__decorate([
+    Delete("plugin-installs/:installId"),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("installId"))
+], OrgCatalogController.prototype, "uninstall", null);
+__decorate([
+    Post("plugin-installs/:installId/upgrade/preview"),
+    HttpCode(200),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("installId")),
+    __param(3, Body(new ZodPipe(UpgradePreviewBody)))
+], OrgCatalogController.prototype, "upgradePreview", null);
+__decorate([
+    Post("plugin-installs/:installId/upgrade"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("installId")),
+    __param(3, Body(new ZodPipe(UpgradeBody))),
+    __param(4, Res({ passthrough: true }))
+], OrgCatalogController.prototype, "upgrade", null);
+__decorate([
+    Post("catalog-requests/:id/decide"),
+    HttpCode(200),
+    OrgAction("catalog.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Body(new ZodPipe(DecideBody)))
+], OrgCatalogController.prototype, "decide", null);
+OrgCatalogController = __decorate([
+    Controller("api/v1/orgs/:orgId"),
+    __param(0, Inject(ORG_CATALOG)),
+    __param(1, Inject(CATALOG_REQUESTS)),
+    __param(2, Inject(PLUGIN_INSTALLER))
+], OrgCatalogController);
+export { OrgCatalogController };
+/** Enterprise admins decide deployment-level catalog requests (`/api/v1/admin/catalog/requests`). */
+let AdminCatalogRequestsController = class AdminCatalogRequestsController {
+    requests;
+    constructor(requests) {
+        this.requests = requests;
+    }
+    async list(q) {
+        return {
+            requests: await this.requests.listDeployment(q.status !== undefined ? { status: q.status } : {}),
+        };
+    }
+    async decide(principal, id, body) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        return {
+            request: await this.requests.decideDeployment(p.account.id, id, body.decision, tokenId !== undefined ? { actorTokenId: tokenId } : {}),
+        };
+    }
+};
+__decorate([
+    Get(),
+    __param(0, Query(new ZodPipe(AdminListQuery)))
+], AdminCatalogRequestsController.prototype, "list", null);
+__decorate([
+    Post(":id/decide"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id")),
+    __param(2, Body(new ZodPipe(DecideBody)))
+], AdminCatalogRequestsController.prototype, "decide", null);
+AdminCatalogRequestsController = __decorate([
+    Controller("api/v1/admin/catalog/requests"),
+    EnterpriseAdmin(),
+    __param(0, Inject(CATALOG_REQUESTS))
+], AdminCatalogRequestsController);
+export { AdminCatalogRequestsController };

package/dist/catalog/org-catalog.service.d.ts

@@ -0,0 +1,246 @@
+import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type LocalizedName, type Logger, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { ExtensionHost } from "../extensions/host.js";
+import { type OrgAction } from "../orgs/roles.js";
+import { checkSkillFiles, type SkillPackageFile } from "../skills/package.js";
+import type { StorageService } from "../storage/storage.service.js";
+import type { ConnectorTemplateRef, CreateConnectorInput } from "../tools/connectors.service.js";
+import { type CatalogItemView } from "./catalog.service.js";
+import type { ConnectorInstallInput, PluginInstaller, PluginInstallInput, PluginInstallView } from "./plugin-install.js";
+import type { PluginUpgradeInput, PluginUpgrader, UpgradePreview } from "./plugin-upgrade.js";
+import type { CatalogRequestsService, CatalogRequestView } from "./requests.service.js";
+type Trx = Transaction<KernelDatabase>;
+/** A catalog item from an organization's view (`GET /orgs/:orgId/catalog`). */
+export interface OrgCatalogItem extends Omit<CatalogItemView, "installs" | "marketplaceId" | "latestMarketplaceVersion" | "newerInMarketplace"> {
+    /**
+     * `yes` installable now; `needs_approval` needs enterprise admin approval (install returns 202 and
+     * creates a request); `granted` approved for this org; `disabled` disabled by the enterprise admin
+     * (members don't see it); `not_deployed` the plugin's extension is not on the deployment.
+     */
+    installable: "yes" | "needs_approval" | "granted" | "disabled" | "not_deployed";
+    /**
+     * This org's live plugin install of the item (installing, installed or upgrading);
+     * `upgradeAvailable` is the version it can be upgraded to now (spec §10), null when none.
+     */
+    installed: {
+        pluginInstallId: string;
+        version: string;
+        upgradeAvailable: string | null;
+    } | null;
+    /** This org's latest request for the item. */
+    request: {
+        id: string;
+        stage: "org" | "deployment";
+        status: string;
+    } | null;
+}
+/**
+ * One connector template in an item's detail (for the install wizard): the endpoint preset, the
+ * paths an org may edit and the auth preset (no credentials). `id` is the template file's base name,
+ * sent as `connectors[id]` in the install body.
+ */
+export interface OrgCatalogTemplate {
+    id: string;
+    displayName: LocalizedName | null;
+    description: string;
+    plugin: string;
+    connector: string;
+    endpoint: Record<string, unknown>;
+    editableEndpoint: string[];
+    auth: Record<string, unknown>;
+    ownership: "org" | "personal" | null;
+}
+/** `GET /orgs/:orgId/catalog/:itemId`: the item and what the install wizard needs (latest version). */
+export interface OrgCatalogDetail {
+    item: OrgCatalogItem;
+    /** The latest version has an icon (`GET .../icon`). */
+    hasIcon: boolean;
+    /** The plugin's extension (its name), null without one. */
+    extension: string | null;
+    templates: OrgCatalogTemplate[];
+    /** The plugin's dependencies (name and range). */
+    dependencies: {
+        name: string;
+        range: string;
+    }[];
+    /** The skill directories. */
+    skills: string[];
+    /** The agent template files (`agents/<name>.md`, sub-agents spec §16). */
+    agents: string[];
+}
+/**
+ * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
+ * presets and editable paths, no credentials.
+ */
+export declare function orgTemplateView(id: string, file: ConnectorTemplateFile): OrgCatalogTemplate;
+/** An item's icon (the latest version's plugin icon). */
+export interface CatalogIcon {
+    data: Uint8Array;
+    contentType: "image/svg+xml" | "image/png";
+    policy: "allow" | "needs_approval" | "disabled";
+}
+/** The parts of a catalog version row an org install reads. */
+export interface CatalogVersionFiles {
+    manifest: unknown;
+    object_prefix: string | null;
+    files: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
+}
+/** Whether the item's latest version has an icon; unreadable counts as none. */
+export declare function catalogHasIcon(db: KernelDb, itemId: string): Promise<boolean>;
+/**
+ * Reads the icon of the item's latest version (served only through kernel routes, with nosniff and
+ * a CSP sandbox in the response headers; the web only shows it with `<img>`). Item missing, deleted
+ * or (when `includeDisabled` is false) disabled -> `catalog.item_not_found` (decided before reading
+ * storage); no icon -> `catalog.icon_not_found`; stored content that is not a valid svg / png
+ * (checked at import, this guards against tampered storage) -> `internal`.
+ */
+export declare function readCatalogIcon(db: KernelDb, storage: StorageService, itemId: string, includeDisabled: boolean): Promise<CatalogIcon>;
+export type { ConnectorInstallInput };
+/** The input of `POST /orgs/:orgId/catalog/:itemId/install` (default version: the latest). */
+export interface OrgInstallInput extends PluginInstallInput {
+    version?: string;
+}
+/** Install result: 201 installed; 202 needs enterprise admin approval, a request was created (or escalated). */
+export type OrgInstallResult = {
+    status: 201;
+    installed: {
+        itemId: string;
+        version: string;
+        pluginInstallId: string;
+    };
+    /** The install view (its components, dependency installs included). */
+    install: PluginInstallView;
+} | {
+    status: 202;
+    request: CatalogRequestView;
+};
+export interface OrgCatalogDeps {
+    db: KernelDb;
+    storage: StorageService;
+    host: Pick<ExtensionHost, "manifests">;
+    /** The connector `kind` provided by extension `plugin` loaded on this replica. */
+    findConnector: TemplateDeps["findConnector"];
+    requests: CatalogRequestsService;
+    pluginInstaller: Pick<PluginInstaller, "install" | "preflight">;
+    pluginUpgrader: Pick<PluginUpgrader, "preview" | "check" | "upgrade">;
+    log?: Pick<Logger, "warn">;
+}
+/** Upgrade result: 200 upgraded (the install view); 202 needs enterprise admin approval, a request was created. */
+export type OrgUpgradeResult = {
+    status: 200;
+    install: PluginInstallView;
+} | {
+    status: 202;
+    request: CatalogRequestView;
+};
+/**
+ * The org actions installing / uninstalling a plugin needs: the union over its components (an
+ * extension -> `org.extensions.manage`, skills -> `skills.manage`, connector templates ->
+ * `connectors.manage`, agent templates -> `agents.manage`), re-checked inside the org row lock.
+ */
+export declare function requiredActions(m: PluginManifest): OrgAction[];
+/** Locks the org row in the caller's transaction and re-checks the actor can do every action (else `forbidden`). */
+export declare function lockOrgForActions(t: Trx, orgId: string, actor: string, actions: OrgAction[]): Promise<void>;
+/** The value at a dot path of `v` (own keys only), undefined when absent. */
+export declare function getPath(v: unknown, path: string): unknown;
+/** Sets the value at a dot path of `obj`, creating the objects on the way. */
+export declare function setPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/** What checking a template's connector extension needs. */
+export interface TemplateDeps {
+    /** The connector `kind` provided by extension `plugin` loaded on this replica. */
+    findConnector: (plugin: string, kind: string) => Connector | undefined;
+    /** The version of an extension loaded on this replica (undefined when not loaded). */
+    pluginVersion: (plugin: string) => string | undefined;
+}
+/**
+ * 模板的连接器插件此刻是否可用：插件加载且提供该 kind，并满足 `pluginVersion`（若写了）；不可用返回原因
+ * （模型不可见，给管理员看的英文）。
+ */
+export declare function templatePluginProblem(d: TemplateDeps, template: ConnectorTemplateSpec): string | undefined;
+/**
+ * Builds the connector install input from a connector template plus what the org filled in (C30):
+ * the endpoint comes from the template, only paths listed in `editableEndpoint` (or fields under
+ * them) may be changed by the org, changing another path -> `validation_failed`; the auth method
+ * comes from the template, the org only gives credentials (static credentials via `credential`,
+ * OAuth via `client`). Re-checks the template's plugin, kind and `pluginVersion` against the
+ * connectors loaded on this replica right now (unmet -> `catalog.not_deployed`); the endpoint
+ * (merged as a whole) schema check, credential pattern check and OAuth URL policy are re-checked by
+ * `ConnectorsService.create`.
+ */
+export declare function templateConnectorInput(deps: TemplateDeps, template: ConnectorTemplateSpec, ref: ConnectorTemplateRef, input: ConnectorInstallInput | undefined, defaultName: string, at?: string): CreateConnectorInput;
+/** 从部署存储读目录版本里的文件（按版本行的 sha256 校验）；`under` 给出时只读该目录下的文件，路径去掉该前缀。 */
+export declare function readCatalogFiles(storage: StorageService, objectPrefix: string | null, files: {
+    path: string;
+    size: number;
+    sha256: string;
+}[], under?: string): Promise<SkillPackageFile[]>;
+/** 校验技能文件并取名字与描述（导入时已校验过；这里防存储被改）。 */
+export declare function skillOf(files: SkillPackageFile[]): ReturnType<typeof checkSkillFiles>;
+/** The connector templates of a catalog version, read from storage (id = the file's base name). */
+export declare function readCatalogTemplates(storage: StorageService, v: CatalogVersionFiles): Promise<{
+    id: string;
+    file: ConnectorTemplateFile;
+}[]>;
+/**
+ * The agent templates of a catalog version (`manifest.agents`, listed explicitly since import),
+ * parsed from storage (checked at import; parsed again in case storage was changed).
+ */
+export declare function readCatalogAgentTemplates(storage: StorageService, v: CatalogVersionFiles): Promise<{
+    path: string;
+    template: AgentTemplate;
+}[]>;
+/**
+ * Organizations browse and install from the enterprise catalog (C22): members browse (without
+ * disabled items) and request, org admins install. Every item is a plugin, installed with its
+ * dependencies by {@link PluginInstaller}; installing requires the union of the component actions
+ * of the plugins it brings in ({@link requiredActions}), re-checked inside the org row lock; item
+ * disabled -> `catalog.item_disabled`; a dependency unresolved / disabled / in a cycle ->
+ * `catalog.dependency_*`; an extension or a template's connector not on the deployment ->
+ * `catalog.not_deployed`; needs_approval without a grant -> a stage deployment request (HTTP 202;
+ * dependencies are not approved separately, spec §10). No in-process state.
+ */
+export declare class OrgCatalogService {
+    private readonly d;
+    constructor(d: OrgCatalogDeps);
+    /** The org's view of the items; members (not admins) don't see disabled items. */
+    list(orgId: string, accountId: string, itemId?: string): Promise<OrgCatalogItem[]>;
+    /**
+     * Item detail (for the install wizard): the same view as the list (members don't see disabled
+     * items, not visible means `catalog.item_not_found`), plus the latest version's extension,
+     * connector templates (endpoint preset, editable paths, auth preset), dependencies, skills and
+     * agent templates.
+     */
+    detail(orgId: string, accountId: string, itemId: string): Promise<OrgCatalogDetail>;
+    /**
+     * The item's icon; members don't see disabled items (-> `catalog.item_not_found`, decided before
+     * reading storage).
+     */
+    icon(itemId: string, isAdmin: boolean): Promise<CatalogIcon>;
+    /** For the admin item detail: whether the latest version has an icon. */
+    hasIcon(itemId: string): Promise<boolean>;
+    /**
+     * The items (latest versions) this replica cannot install now: the plugin's extension is not
+     * loaded, or a connector template's connector extension is not (or not at the template's
+     * `pluginVersion`). Dependencies are judged at install. A template that cannot be read counts as
+     * deployed here (the install reads it again).
+     */
+    private undeployed;
+    /** Installs a plugin in the org (see the class comment). */
+    install(orgId: string, actor: string, itemId: string, body: OrgInstallInput, actorTokenId?: string): Promise<OrgInstallResult>;
+    /** The upgrade preview of an org install (spec §10, see `PluginUpgrader`). */
+    upgradePreview(orgId: string, actor: string, installId: string, version: string): Promise<UpgradePreview>;
+    /**
+     * Upgrades an org install in place (spec §10, Decision 11): the preview's `diffHash` is checked
+     * first (`plugin.upgrade_stale`); the item disabled -> `catalog.item_disabled`; needs_approval
+     * without a grant -> a stage deployment request for the target version (202; after approval the
+     * org admin runs the upgrade again); otherwise the upgrade runs (200, the install view).
+     */
+    upgrade(orgId: string, actor: string, installId: string, body: PluginUpgradeInput, actorTokenId?: string): Promise<OrgUpgradeResult>;
+    /** The actor can install something in the org (forbidden otherwise), checked before item errors. */
+    private assertCanInstall;
+}