@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/catalog/org-extension-switch.d.ts

@@ -0,0 +1,41 @@
+import { OrgExtensionConfigs, type OrgExtensionInput, type OrgExtensionView } from "../extensions/org-config.js";
+import { OrgCatalogService } from "./org-catalog.service.js";
+import type { UninstallPreview } from "./plugin-install.js";
+/** The result of {@link OrgExtensionSwitch.put}: the extension, or the plugin uninstall preview. */
+export type OrgExtensionPutResult = {
+    kind: "done";
+    view: OrgExtensionView;
+} | {
+    kind: "preview";
+    preview: UninstallPreview;
+    confirm: string;
+};
+/**
+ * `PUT orgs/:orgId/extensions/:extension`: for an extension that ships in a catalog plugin, `enabled`
+ * is the plugin's org switch ({@link OrgCatalogService.setSwitch}); anything else is the direct
+ * {@link OrgExtensionConfigs.put}. Lives in the catalog module because the catalog depends on the
+ * extensions, not the other way round. No in-process state.
+ *
+ * Order: the config is validated first (`validateOnly`: no side effect), so an invalid config fails
+ * before the plugin switches with the plain 400 `extension.config_invalid`. Switching on validates
+ * the effective config (the stored one with its secrets, or the given `config` merged with them),
+ * and the install receives the given `config` as its `extensionConfig`, so the extension is enabled
+ * with it. A config write that fails for another reason after the switch succeeded returns that
+ * error with the switch done (the two writes are separate transactions).
+ */
+export declare class OrgExtensionSwitch {
+    private readonly configs;
+    private readonly catalog;
+    constructor(configs: OrgExtensionConfigs, catalog: OrgCatalogService);
+    /**
+     * - `enabled` on an extension of one catalog plugin: that plugin's switch; off without `confirm`
+     *   returns the preview and its hash, with the hash uninstalls; a builtin plugin (any of several
+     *   source items) -> 409 `plugin.scope_locked` (an `all` one may go off, layering spec §4).
+     * - A required bootstrap plugin, a config-declared extension and one sourced from several items
+     *   keep the direct write.
+     * - `config` is always written directly, after the switch.
+     */
+    put(orgId: string, actor: string, extension: string, body: OrgExtensionInput & {
+        confirm?: string | undefined;
+    }, actorTokenId?: string): Promise<OrgExtensionPutResult>;
+}

package/dist/catalog/org-extension-switch.js

@@ -0,0 +1,115 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { OrgExtensionConfigs, } from "../extensions/org-config.js";
+import { OrgCatalogService } from "./org-catalog.service.js";
+/**
+ * `PUT orgs/:orgId/extensions/:extension`: for an extension that ships in a catalog plugin, `enabled`
+ * is the plugin's org switch ({@link OrgCatalogService.setSwitch}); anything else is the direct
+ * {@link OrgExtensionConfigs.put}. Lives in the catalog module because the catalog depends on the
+ * extensions, not the other way round. No in-process state.
+ *
+ * Order: the config is validated first (`validateOnly`: no side effect), so an invalid config fails
+ * before the plugin switches with the plain 400 `extension.config_invalid`. Switching on validates
+ * the effective config (the stored one with its secrets, or the given `config` merged with them),
+ * and the install receives the given `config` as its `extensionConfig`, so the extension is enabled
+ * with it. A config write that fails for another reason after the switch succeeded returns that
+ * error with the switch done (the two writes are separate transactions).
+ */
+let OrgExtensionSwitch = class OrgExtensionSwitch {
+    configs;
+    catalog;
+    constructor(configs, catalog) {
+        this.configs = configs;
+        this.catalog = catalog;
+    }
+    /**
+     * - `enabled` on an extension of one catalog plugin: that plugin's switch; off without `confirm`
+     *   returns the preview and its hash, with the hash uninstalls; a builtin plugin (any of several
+     *   source items) -> 409 `plugin.scope_locked` (an `all` one may go off, layering spec §4).
+     * - A required bootstrap plugin, a config-declared extension and one sourced from several items
+     *   keep the direct write.
+     * - `config` is always written directly, after the switch.
+     */
+    async put(orgId, actor, extension, body, actorTokenId) {
+        const { confirm, ...input } = body;
+        const plan = input.enabled === undefined
+            ? { kind: "direct" }
+            : await this.configs.switchPlan(extension, input.enabled);
+        if (plan.kind === "locked") {
+            throw new ApiError("plugin.scope_locked", "This plugin is built in: it is on for every organization and cannot be switched off here");
+        }
+        if (plan.kind === "direct") {
+            return {
+                kind: "done",
+                view: await this.configs.put(orgId, extension, input, actor, actorTokenId),
+            };
+        }
+        const { enabled } = input;
+        const config = input.config !== undefined ? { config: input.config } : {};
+        // Fail before the switch when the config would be refused: switching on checks the effective
+        // config (a required field never saved is refused here, not as a failed install)
+        if (enabled || input.config !== undefined) {
+            await this.configs.put(orgId, extension, { ...config, ...(enabled && { enabled: true }) }, actor, actorTokenId, { validateOnly: true });
+        }
+        const r = await this.catalog
+            .setSwitch(orgId, actor, plan.itemId, enabled
+            ? {
+                enabled: true,
+                ...(input.config !== undefined && { inputs: { extensionConfig: input.config } }),
+            }
+            : { enabled: false, ...(confirm !== undefined && { confirm }) }, actorTokenId)
+            .catch((e) => {
+            throw configInvalidOf(e) ?? e;
+        });
+        if (r.kind === "preview")
+            return r;
+        if (input.config === undefined) {
+            if (!enabled) {
+                const view = (await this.configs.list(orgId)).find((v) => v.plugin === extension);
+                if (view)
+                    return { kind: "done", view };
+            }
+            // Switching on: the install enabled it already (no second write)
+            return {
+                kind: "done",
+                view: await this.configs.put(orgId, extension, { enabled: true }, actor, actorTokenId, {
+                    ifDisabled: { skipped: false },
+                }),
+            };
+        }
+        return {
+            kind: "done",
+            view: await this.configs.put(orgId, extension, { config: input.config, ...(enabled && { enabled: true }) }, actor, actorTokenId),
+        };
+    }
+};
+OrgExtensionSwitch = __decorate([
+    Injectable(),
+    __param(0, Inject(OrgExtensionConfigs)),
+    __param(1, Inject(OrgCatalogService))
+], OrgExtensionSwitch);
+export { OrgExtensionSwitch };
+/**
+ * An install that failed only at its own extension step on the org config (it was valid when
+ * checked, then changed concurrently): the plain 400 `extension.config_invalid` with the field
+ * issues, as when saving the config; the install was rolled back. Anything else: undefined.
+ */
+function configInvalidOf(e) {
+    if (!(e instanceof ApiError) || e.code !== "plugin.install_failed")
+        return undefined;
+    const [d] = (e.details ?? []);
+    if (d?.step !== "extension" || d.code !== "extension.config_invalid")
+        return undefined;
+    if (d.dependency !== undefined || d.rolledBack !== true)
+        return undefined;
+    return new ApiError("extension.config_invalid", d.message ?? "Invalid organization config", d.causeDetails);
+}

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

@@ -0,0 +1,119 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { OrgExtensionConfigs, type OrgExtensionView } from "../extensions/org-config.js";
+import { OrgOverrides, type OrgOverrideView } from "../extensions/org-overrides.js";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type OrgToolSwitch, OrgToolSwitches, type OrgToolSwitchResult } from "../tools/org-tool-switches.js";
+import { OrgExtensionSwitch } from "./org-extension-switch.js";
+import type { UninstallPreview } from "./plugin-install.js";
+declare const PutBody: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    force: z.ZodOptional<z.ZodBoolean>;
+    confirm: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const OverridesPut: z.ZodObject<{
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    secretEntries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        key: z.ZodString;
+        value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        renameFrom: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+declare const OverridesTake: z.ZodObject<{
+    paths: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+declare const ToolSwitchPut: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    confirm: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Route parameters of the overrides and tool switch routes (decision R20). */
+declare const ExtensionParams: z.ZodObject<{
+    extension: z.ZodString;
+}, z.core.$strip>;
+declare const ToolParams: z.ZodObject<{
+    extension: z.ZodString;
+    tool: z.ZodString;
+}, z.core.$strip>;
+/**
+ * One extension of the org list: the org view plus the plugin's display name and the extension
+ * points it provides (`channel@1`, `web-search@1`, … the names only, also for members).
+ */
+export type OrgExtensionItem = OrgExtensionView & {
+    displayName: LocalizedName | null;
+    provides: string[];
+};
+/**
+ * What a member sees of an extension: its state and the points it provides (names only, what the
+ * 扩展 page sorts by), never the org config, the secrets' state, the config schema or the
+ * permission list.
+ */
+export type OrgExtensionMemberItem = Omit<OrgExtensionItem, "config" | "secrets" | "orgConfigSchema" | "permissions">;
+/**
+ * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
+ * non-secret config and whether each secret is set.
+ */
+export declare class OrgExtensionConfigsController {
+    private readonly configs;
+    private readonly displayNames;
+    private readonly extSwitch;
+    constructor(configs: OrgExtensionConfigs, displayNames: ExtensionDisplayNames, extSwitch: OrgExtensionSwitch);
+    /**
+     * The org's extensions (also the channel plugin options: those providing `channel@1`). Members
+     * get the projection {@link OrgExtensionMemberItem}; admins the full view.
+     */
+    list(org: OrgContext): Promise<{
+        extensions: OrgExtensionItem[] | OrgExtensionMemberItem[];
+    }>;
+    /**
+     * Writes enablement and / or config; see {@link OrgExtensionSwitch.put} for how `enabled` follows
+     * the extension's plugin (off answers `{ preview, confirm }` until `confirm` carries the hash).
+     */
+    put(principal: Principal, org: OrgContext, extension: string, body: z.infer<typeof PutBody>): Promise<{
+        extension: OrgExtensionItem;
+    } | {
+        preview: UninstallPreview;
+        confirm: string;
+    }>;
+}
+/**
+ * The org's two-level deployment config of an extension (spec A §5.3 to §5.6): following or a copy,
+ * the read-only and overridable fields (hidden ones are never sent), secrets as set or not.
+ */
+export declare class OrgExtensionOverridesController {
+    private readonly overrides;
+    constructor(overrides: OrgOverrides);
+    view(org: OrgContext, { extension }: z.infer<typeof ExtensionParams>): Promise<OrgOverrideView>;
+    /**
+     * Saves overridable fields; the first save makes the copy, which must be valid on its own (the
+     * org's own secrets in the same save). A read-only, hidden or unknown field -> 400
+     * `extension.field_not_overridable`; invalid -> 400 `extension.config_invalid`.
+     */
+    save(principal: Principal, org: OrgContext, { extension }: z.infer<typeof ExtensionParams>, body: z.infer<typeof OverridesPut>): Promise<OrgOverrideView>;
+    /** Drops the copy (its secrets too): the org follows the platform again. */
+    reset(principal: Principal, org: OrgContext, { extension }: z.infer<typeof ExtensionParams>): Promise<OrgOverrideView>;
+    /** Takes the platform's current values of non-secret overridable fields into the copy. */
+    take(principal: Principal, org: OrgContext, { extension }: z.infer<typeof ExtensionParams>, body: z.infer<typeof OverridesTake>): Promise<OrgOverrideView>;
+}
+/**
+ * The org's switches of an extension's single tools (layering spec A §7): members read them, org
+ * admins turn a tool off (previewed with the agents that selected it, PCM §5 rule 8) or on.
+ */
+export declare class OrgExtensionToolSwitchesController {
+    private readonly switches;
+    constructor(switches: OrgToolSwitches);
+    /** Every tool the extension registers, with its switch (on unless the org turned it off). */
+    list(org: OrgContext, { extension }: z.infer<typeof ExtensionParams>): Promise<{
+        tools: OrgToolSwitch[];
+    }>;
+    /**
+     * Switches one tool: on applies at once; off answers `{ applied: false, affectedAgents, confirm }`
+     * until `confirm` carries the hash (a changed preview -> 409 `plugin.switch_stale`). A tool the
+     * extension does not register -> 404 `extension.tool_not_found`.
+     */
+    set(principal: Principal, org: OrgContext, { extension, tool }: z.infer<typeof ToolParams>, body: z.infer<typeof ToolSwitchPut>): Promise<OrgToolSwitchResult>;
+}
+export {};

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

@@ -0,0 +1,266 @@
+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 { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put } from "@nestjs/common";
+import { z } from "zod";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { OrgExtensionConfigs, providesOf, } from "../extensions/org-config.js";
+import { OrgOverrides } from "../extensions/org-overrides.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { roleAtLeast } from "../orgs/roles.js";
+import { OrgToolSwitches, } from "../tools/org-tool-switches.js";
+import { OrgExtensionSwitch } from "./org-extension-switch.js";
+const PutBody = z
+    .object({
+    enabled: z.boolean().optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+    force: z.boolean().optional(),
+    /** The hash of the plugin uninstall preview, to confirm switching the extension's plugin off. */
+    confirm: z.string().optional(),
+})
+    .strict();
+class OrgExtensionPutBody extends createZodDto(PutBody, "OrgExtensionPutBody") {
+}
+const OverrideSecretEntry = z
+    .object({
+    /** A secret record field of the copy some `x-ui.secrets[].path` names. */
+    path: z.string().min(1).max(256),
+    key: z.string().min(1).max(256),
+    /** A string sets the key, `null` removes it. */
+    value: z.string().max(65_536).nullable().optional(),
+    /** Moves the value at this key to `key` first. */
+    renameFrom: z.string().min(1).max(256).optional(),
+})
+    .strict()
+    .refine((e) => e.value !== undefined || e.renameFrom !== undefined, {
+    message: "an entry needs value or renameFrom",
+})
+    .refine((e) => e.key !== "__proto__" && e.renameFrom !== "__proto__", {
+    message: "__proto__ is not a valid key",
+});
+const OverridesPut = z
+    .object({
+    /** Overridable field dot path -> new value (`null` clears); secret fields too. */
+    values: z.record(z.string().min(1).max(256), z.unknown()),
+    secretEntries: z.array(OverrideSecretEntry).max(200).optional(),
+})
+    .strict();
+const OverridesTake = z
+    .object({ paths: z.array(z.string().min(1).max(256)).min(1).max(200) })
+    .strict();
+const ToolSwitchPut = z
+    .object({
+    enabled: z.boolean(),
+    /** The hash of the switch-off preview, to confirm turning the tool off. */
+    confirm: z.string().min(1).max(128).optional(),
+})
+    .strict();
+class OrgToolSwitchPutBody extends createZodDto(ToolSwitchPut, "OrgToolSwitchPutBody") {
+}
+/** Route parameters of the overrides and tool switch routes (decision R20). */
+const ExtensionParams = z.object({ extension: z.string().min(1).max(64) });
+const ToolParams = ExtensionParams.extend({ tool: z.string().min(1).max(64) });
+class OrgExtensionParamsDto extends createZodDto(ExtensionParams, "OrgExtensionParams") {
+}
+class OrgExtensionToolParamsDto extends createZodDto(ToolParams, "OrgExtensionToolParams") {
+}
+class OrgOverridesPutBody extends createZodDto(OverridesPut, "OrgOverridesPutBody") {
+}
+class OrgOverridesTakeBody extends createZodDto(OverridesTake, "OrgOverridesTakeBody") {
+}
+/**
+ * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
+ * non-secret config and whether each secret is set.
+ */
+let OrgExtensionConfigsController = class OrgExtensionConfigsController {
+    configs;
+    displayNames;
+    extSwitch;
+    constructor(configs, displayNames, extSwitch) {
+        this.configs = configs;
+        this.displayNames = displayNames;
+        this.extSwitch = extSwitch;
+    }
+    /**
+     * The org's extensions (also the channel plugin options: those providing `channel@1`). Members
+     * get the projection {@link OrgExtensionMemberItem}; admins the full view.
+     */
+    async list(org) {
+        const views = await this.configs.list(org.orgId);
+        const names = await this.displayNames.many(views.map((v) => v.plugin));
+        const items = views.map((v) => ({
+            ...v,
+            displayName: names.get(v.plugin) ?? null,
+            provides: providesOf(v),
+        }));
+        if (roleAtLeast(org.role, "admin"))
+            return { extensions: items };
+        return {
+            extensions: items.map(({ config: _c, secrets: _s, orgConfigSchema: _o, permissions: _p, ...rest }) => rest),
+        };
+    }
+    /**
+     * Writes enablement and / or config; see {@link OrgExtensionSwitch.put} for how `enabled` follows
+     * the extension's plugin (off answers `{ preview, confirm }` until `confirm` carries the hash).
+     */
+    async put(principal, org, extension, body) {
+        const p = requireUser(principal);
+        const r = await this.extSwitch.put(org.orgId, p.account.id, extension, body, patTokenId(p));
+        if (r.kind === "preview")
+            return { preview: r.preview, confirm: r.confirm };
+        return {
+            extension: {
+                ...r.view,
+                displayName: await this.displayNames.get(r.view.plugin),
+                provides: providesOf(r.view),
+            },
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.extensions.read"),
+    __param(0, CurrentOrg())
+], OrgExtensionConfigsController.prototype, "list", null);
+__decorate([
+    Put(":extension"),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("extension")),
+    __param(3, ZBody(OrgExtensionPutBody))
+], OrgExtensionConfigsController.prototype, "put", null);
+OrgExtensionConfigsController = __decorate([
+    Controller("api/v1/orgs/:orgId/extensions"),
+    __param(0, Inject(OrgExtensionConfigs)),
+    __param(1, Inject(ExtensionDisplayNames)),
+    __param(2, Inject(OrgExtensionSwitch))
+], OrgExtensionConfigsController);
+export { OrgExtensionConfigsController };
+/**
+ * The org's two-level deployment config of an extension (spec A §5.3 to §5.6): following or a copy,
+ * the read-only and overridable fields (hidden ones are never sent), secrets as set or not.
+ */
+let OrgExtensionOverridesController = class OrgExtensionOverridesController {
+    overrides;
+    constructor(overrides) {
+        this.overrides = overrides;
+    }
+    view(org, { extension }) {
+        return this.overrides.view(org.orgId, extension);
+    }
+    /**
+     * Saves overridable fields; the first save makes the copy, which must be valid on its own (the
+     * org's own secrets in the same save). A read-only, hidden or unknown field -> 400
+     * `extension.field_not_overridable`; invalid -> 400 `extension.config_invalid`.
+     */
+    save(principal, org, { extension }, body) {
+        const p = requireUser(principal);
+        return this.overrides.save(org.orgId, extension, body.values, body.secretEntries ?? [], {
+            accountId: p.account.id,
+            tokenId: patTokenId(p),
+        });
+    }
+    /** Drops the copy (its secrets too): the org follows the platform again. */
+    reset(principal, org, { extension }) {
+        const p = requireUser(principal);
+        return this.overrides.reset(org.orgId, extension, {
+            accountId: p.account.id,
+            tokenId: patTokenId(p),
+        });
+    }
+    /** Takes the platform's current values of non-secret overridable fields into the copy. */
+    take(principal, org, { extension }, body) {
+        const p = requireUser(principal);
+        return this.overrides.take(org.orgId, extension, body.paths, {
+            accountId: p.account.id,
+            tokenId: patTokenId(p),
+        });
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentOrg()),
+    __param(1, ZParam(OrgExtensionParamsDto))
+], OrgExtensionOverridesController.prototype, "view", null);
+__decorate([
+    Put(),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgExtensionParamsDto)),
+    __param(3, ZBody(OrgOverridesPutBody))
+], OrgExtensionOverridesController.prototype, "save", null);
+__decorate([
+    Delete(),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgExtensionParamsDto))
+], OrgExtensionOverridesController.prototype, "reset", null);
+__decorate([
+    Post("take"),
+    HttpCode(200),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgExtensionParamsDto)),
+    __param(3, ZBody(OrgOverridesTakeBody))
+], OrgExtensionOverridesController.prototype, "take", null);
+OrgExtensionOverridesController = __decorate([
+    Controller("api/v1/orgs/:orgId/extensions/:extension/overrides"),
+    __param(0, Inject(OrgOverrides))
+], OrgExtensionOverridesController);
+export { OrgExtensionOverridesController };
+/**
+ * The org's switches of an extension's single tools (layering spec A §7): members read them, org
+ * admins turn a tool off (previewed with the agents that selected it, PCM §5 rule 8) or on.
+ */
+let OrgExtensionToolSwitchesController = class OrgExtensionToolSwitchesController {
+    switches;
+    constructor(switches) {
+        this.switches = switches;
+    }
+    /** Every tool the extension registers, with its switch (on unless the org turned it off). */
+    async list(org, { extension }) {
+        return { tools: await this.switches.list(org.orgId, extension) };
+    }
+    /**
+     * Switches one tool: on applies at once; off answers `{ applied: false, affectedAgents, confirm }`
+     * until `confirm` carries the hash (a changed preview -> 409 `plugin.switch_stale`). A tool the
+     * extension does not register -> 404 `extension.tool_not_found`.
+     */
+    set(principal, org, { extension, tool }, body) {
+        const p = requireUser(principal);
+        return this.switches.set(org.orgId, extension, tool, body.enabled, { accountId: p.account.id, tokenId: patTokenId(p) }, body.confirm);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.extensions.read"),
+    __param(0, CurrentOrg()),
+    __param(1, ZParam(OrgExtensionParamsDto))
+], OrgExtensionToolSwitchesController.prototype, "list", null);
+__decorate([
+    Put(":tool"),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgExtensionToolParamsDto)),
+    __param(3, ZBody(OrgToolSwitchPutBody))
+], OrgExtensionToolSwitchesController.prototype, "set", null);
+OrgExtensionToolSwitchesController = __decorate([
+    Controller("api/v1/orgs/:orgId/extensions/:extension/tools"),
+    __param(0, Inject(OrgToolSwitches))
+], OrgExtensionToolSwitchesController);
+export { OrgExtensionToolSwitchesController };

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

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { CatalogItemView } from "./catalog.service.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
+import { OrgPluginUploads, type OrgUploadOutcome, type OrgUploadReview } from "./org-plugin-uploads.js";
+import { type OwnedDeletePreview, OwnedItems } from "./owned-items.js";
+declare const StagingParams: z.ZodObject<{
+    stagingId: z.ZodString;
+}, z.core.$strip>;
+declare const OwnedParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const ConfirmBody: z.ZodObject<{
+    reviewHash: z.ZodString;
+    shareable: z.ZodOptional<z.ZodBoolean>;
+    pinnedSuggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const ShareableBody: z.ZodObject<{
+    shareable: z.ZodBoolean;
+}, z.core.$strict>;
+declare const DeleteBody: z.ZodObject<{
+    previewHash: z.ZodString;
+}, z.core.$strict>;
+/**
+ * An org admin's plugin uploads (`/api/v1/orgs/:orgId/catalog/uploads/*`, spec §14, rulings P3-7,
+ * P3-8): a `.tgz` without an extension, prepared (one review) and confirmed like the super admin's
+ * import, owned by the org. Writes re-check the org admin under the org row lock.
+ */
+export declare class OrgPluginUploadsController {
+    private readonly uploads;
+    constructor(uploads: OrgPluginUploads);
+    /**
+     * Prepares an upload (the tgz as the raw body, `application/octet-stream`, at most
+     * `packages.maxBytes`): `{ stagingId, review, update }`, the staging kept 24 hours for this org.
+     * The checks of the platform import, plus: `customSkills` = deny with skills or agent templates,
+     * or `customConnectors` = deny with connector templates -> 403 `catalog.custom_disabled`
+     * (ruling P3-15'); a name live for another owner -> 409 `plugin.name_taken` (details
+     * `[{ owner }]`); a dependency the org cannot use -> 409 `plugin.dependency_unavailable`
+     * (details `[{ dependencies }]`).
+     */
+    upload(principal: Principal, org: OrgContext, req: {
+        body?: unknown;
+    }): Promise<OrgUploadReview>;
+    /** The org's staged upload; unknown, expired, confirmed, another org's or the platform's -> 404. */
+    staged(org: OrgContext, params: z.infer<typeof StagingParams>): Promise<OrgUploadReview>;
+    /**
+     * Confirms the org's staged upload (201 `{ item, outcome }`): a new item owned by the org, scope
+     * `named: [org]`, not shown to other orgs, `shareable` as sent (default false), installed in the
+     * org by the scope sync (`installed`); a new version of its own item (`updated`). The checks of
+     * prepare run again under the item name's lock (the first confirm of a name wins). A package
+     * with an extension waits for the super admin (`pending`, ruling P3-10): stored, its extension
+     * name claimed (another package's -> 409 `extension.name_conflict` naming the owner), nothing
+     * installed or usable until confirmed in 待确认; a later upload replaces the pending version
+     * (P3-11). A version without an extension for an item whose first version still waits replaces
+     * that upload and is installed at once (`installed`).
+     */
+    confirm(principal: Principal, org: OrgContext, params: z.infer<typeof StagingParams>, body: z.infer<typeof ConfirmBody>): Promise<{
+        item: CatalogItemView;
+        outcome: OrgUploadOutcome;
+    }>;
+}
+/**
+ * The org's own plugins (`/api/v1/orgs/:orgId/owned-plugins/*`, spec §14, P3-17 to P3-19): the
+ * owner org's admin withdraws a pending upload, toggles 可共享 and deletes the plugin after a
+ * preview. Another org's or a platform plugin -> 404. Writes re-check the org admin under the org
+ * row lock.
+ */
+export declare class OrgOwnedPluginsController {
+    private readonly scope;
+    private readonly owned;
+    constructor(scope: CatalogScopeService, owned: OwnedItems);
+    /**
+     * Sets 可共享 (ruling P3-2: the plugin and its component rows in one transaction; turning it
+     * off keeps the orgs already associated and hides it from new ones, ruling P3-25). 204.
+     */
+    setShareable(principal: Principal, org: OrgContext, params: z.infer<typeof OwnedParams>, body: z.infer<typeof ShareableBody>): Promise<void>;
+    /**
+     * What deleting the plugin does (P3-19, nothing written): `outcome` `removed` (no other org
+     * uses it) or `transferred` (to the platform), `orgs` the other orgs using it, `agents` the
+     * org's agents that lose it, and the `previewHash` to confirm.
+     */
+    previewDelete(org: OrgContext, params: z.infer<typeof OwnedParams>): Promise<OwnedDeletePreview>;
+    /**
+     * Deletes the plugin after its preview: removed, or transferred to the platform when another
+     * org uses it (platform notice `ownership_transferred`). A preview that changed meanwhile ->
+     * 409 `catalog.preview_stale`. 204.
+     */
+    delete(principal: Principal, org: OrgContext, params: z.infer<typeof OwnedParams>, body: z.infer<typeof DeleteBody>): Promise<void>;
+    /**
+     * Withdraws the org's pending upload of the plugin (ruling P3-10, no notice): a first version
+     * is removed (its name free again), a new version's pending state cleared (the platform version
+     * keeps running). Another org's or a platform plugin -> 404; nothing pending -> 409
+     * `extension.not_pending`. 204.
+     */
+    withdraw(principal: Principal, org: OrgContext, params: z.infer<typeof OwnedParams>): Promise<void>;
+}
+export {};