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

package/dist/platform/ops/platform.ops.js

@@ -0,0 +1,158 @@
+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 { extensionToolKey } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { AgentsService } from "../../agents/agents.service.js";
+import { can } from "../../orgs/roles.js";
+import { effectiveSandboxEgress, OrgSettingsService } from "../../orgs/settings.service.js";
+import { SANDBOX_TOOL_NAMES } from "../../tools/builtin-names.js";
+import { ToolRegistry } from "../../tools/registry.js";
+import { PlatformActor } from "../actor.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { asToolError } from "./errors.js";
+/** What a role may build, as the model says it to the person: the action and its plain words. */
+const BUILDS = [
+    { action: "agents.create", what: "create private agents and edit the agents you own" },
+    { action: "skills.manage", what: "create org skills" },
+    { action: "agents.manage", what: "manage other people's agents and save org agent templates" },
+    { action: "connectors.manage", what: "set up connectors" },
+    { action: "org.extensions.manage", what: "manage extensions" },
+];
+const FAMILIES = [
+    "Platform: this tool, for the org's skills, agents, agent templates, plugins, connectors and requests.",
+    "Skill and SkillWrite: use and write the skills of this agent.",
+    "Agent, SendMessage, SubagentHandback: dispatch and talk to sub-agents.",
+    "Bash, Read, Write, Edit, Glob, Grep, Deliver: work in the conversation's sandbox.",
+    "WebSearch, WebFetch: reach the web through the org's providers.",
+    "Plugin and connector tools, named plugin__<plugin>__<tool> and mcp__<connector>__<tool>.",
+];
+const EMPTY = z.object({}).strict();
+/** The `platform` domain: orientation, and what this agent is (spec §7). Synthetic, no route. */
+let PlatformOperationsProvider = class PlatformOperationsProvider {
+    registry;
+    actor;
+    agents;
+    settings;
+    tools;
+    constructor(registry, actor, agents, settings, tools) {
+        this.registry = registry;
+        this.actor = actor;
+        this.agents = agents;
+        this.settings = settings;
+        this.tools = tools;
+    }
+    /**
+     * The agent's tools by the keys the model sees: builtins by name, plugin tools as
+     * `plugin__<plugin>__<tool>`, and each connector reference expanded to its live tools'
+     * `mcp__<slug>__<tool>` keys as the registry resolves them for a run; connector tools that
+     * cannot load now are listed with the registry's reason.
+     */
+    async toolKeys(orgId, d) {
+        const connectors = d.tools.filter((r) => r.kind === "connector");
+        const resolved = connectors.length === 0
+            ? { tools: [], unavailable: [] }
+            : await this.tools.forAgent(orgId, { tools: connectors });
+        const live = new Map();
+        for (const t of resolved.tools) {
+            if (t.source.kind !== "connector")
+                continue;
+            live.set(t.source.connectorId, [...(live.get(t.source.connectorId) ?? []), t.key]);
+        }
+        const keys = d.tools.flatMap((r) => r.kind === "connector"
+            ? (live.get(r.connectorId) ?? [])
+            : [r.kind === "builtin" ? r.name : extensionToolKey(r.plugin, r.name)]);
+        return {
+            keys: [...new Set(keys)],
+            unavailable: resolved.unavailable.map((u) => ({ tool: u.ref, reason: u.reason })),
+        };
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "platform.overview",
+                description: "Explain what the platform is, the tool families you have, your role in this org and what that role may build, and the operation domains to browse. Start here when asked what you can do on the platform.",
+                input: EMPTY,
+                example: {},
+                authz: { orgAction: "org.read" },
+                mirrors: [],
+                confirm: "read",
+                run: async (_input, ctx) => {
+                    const facts = await this.actor.facts({
+                        orgId: ctx.orgId,
+                        accountId: ctx.actorAccountId,
+                        agentId: ctx.agentId,
+                        conversationId: ctx.conversationId,
+                        runId: ctx.runId,
+                    });
+                    const role = facts.role;
+                    return {
+                        platform: "Capybara is an enterprise agent platform: orgs of people build and use agents that work with skills, tools and connectors. Everything it can do is offered by extensions and plugins.",
+                        toolFamilies: FAMILIES,
+                        you: {
+                            role,
+                            isSuperAdmin: facts.isSuperAdmin,
+                            canBuild: role === null ? [] : BUILDS.filter((b) => can(role, b.action)).map((b) => b.what),
+                            platformToolSetting: facts.setting,
+                            personPresent: facts.personPresent,
+                        },
+                        domains: this.registry.domains(),
+                        next: 'Use action "browse" with a domain to see its operations, then "describe" before "call".',
+                    };
+                },
+            }),
+            defineOperation({
+                id: "platform.me",
+                description: "Show this agent as configured: its model, tools by the keys you call them by (connector tools as mcp__<connector>__<tool>, with those that cannot load now and why), skills (org and pinned), sub-agents, whether it runs in a sandbox, and the sandbox network mode. Secrets are never shown.",
+                input: EMPTY,
+                example: {},
+                authz: { orgAction: "agents.use" },
+                mirrors: [],
+                confirm: "read",
+                run: async (_input, ctx) => asToolError(async () => {
+                    const agent = await this.agents.get(ctx.orgId, ctx.agentId, ctx.actorAccountId);
+                    const d = agent.definition;
+                    const { keys: toolKeys, unavailable } = await this.toolKeys(ctx.orgId, d);
+                    const sandbox = toolKeys.some((k) => SANDBOX_TOOL_NAMES.includes(k));
+                    const org = await this.settings.get(ctx.orgId);
+                    const dep = this.settings.deployment().sandboxEgress;
+                    const egress = effectiveSandboxEgress({ egress: dep.mode, allowHosts: dep.allowHosts }, org.sandboxEgress);
+                    return {
+                        id: agent.id,
+                        name: d.name,
+                        visibility: agent.visibility,
+                        version: agent.currentVersion,
+                        model: d.model,
+                        fallback: d.fallback,
+                        tools: toolKeys,
+                        ...(unavailable.length > 0 && { unavailableTools: unavailable }),
+                        toolPolicies: d.toolPolicies,
+                        skills: {
+                            orgSkills: d.skills?.orgSkills ?? [],
+                            pinned: d.skills?.pinned ?? [],
+                        },
+                        subagents: d.subagents ?? null,
+                        sandbox: sandbox ? { enabled: true, egress: egress.egress } : { enabled: false },
+                    };
+                }),
+            }),
+        ]);
+    }
+};
+PlatformOperationsProvider = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(PlatformActor)),
+    __param(2, Inject(AgentsService)),
+    __param(3, Inject(OrgSettingsService)),
+    __param(4, Inject(ToolRegistry))
+], PlatformOperationsProvider);
+export { PlatformOperationsProvider };

package/dist/platform/ops/plugins.ops.d.ts

@@ -0,0 +1,33 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { CatalogService } from "../../catalog/catalog.service.js";
+import { OrgCatalogService } from "../../catalog/org-catalog.service.js";
+import { PluginInstaller } from "../../catalog/plugin-install.js";
+import { PlatformPluginUpdater } from "../../catalog/plugin-upgrade.js";
+import { OrgExtensionConfigs } from "../../extensions/org-config.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { PlatformOperations } from "../registry.js";
+export declare const OTHER_ORG = "This plugin belongs to another org; use the admin console.";
+export declare const NEEDS_INPUT = "This plugin needs configuration a person must enter; ask them to enable it on the \u63D2\u4EF6 page.";
+/**
+ * Plugin operations of the `Platform` tool (spec §7): the org's view (list, get, switch on or off)
+ * and the super admin's platform view (list, get, update with its preview). Every platform result
+ * goes through {@link redactOrgs}: other orgs only as counts (spec §6.1).
+ */
+export declare class PluginsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly orgCatalog;
+    private readonly catalog;
+    private readonly updater;
+    private readonly installer;
+    private readonly extensions;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, orgCatalog: OrgCatalogService, catalog: CatalogService, updater: PlatformPluginUpdater, installer: PluginInstaller, extensions: OrgExtensionConfigs, kdb: KernelDb);
+    /**
+     * Refuses a super-admin operation on an item another org owns: its results would describe that
+     * org's private plugin in this org's log (spec §6.1). Platform items and the org's own pass.
+     */
+    private assertNotOtherOrgs;
+    /** How many live catalog items other orgs own (left out of the platform list). */
+    private otherOrgItems;
+    onModuleInit(): void;
+}

package/dist/platform/ops/plugins.ops.js

@@ -0,0 +1,377 @@
+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 { ToolError } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { CatalogService } from "../../catalog/catalog.service.js";
+import { OrgCatalogService } from "../../catalog/org-catalog.service.js";
+import { PluginInstaller, uninstallPreviewHash } from "../../catalog/plugin-install.js";
+import { PlatformPluginUpdater } from "../../catalog/plugin-upgrade.js";
+import { OrgExtensionConfigs } from "../../extensions/org-config.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { defineOperation } from "../operation.js";
+import { redactOrgs } from "../redact-orgs.js";
+import { PlatformOperations } from "../registry.js";
+import { asToolError, viaAgent } from "./errors.js";
+import { Cursor, pageOf, startOf } from "./paging.js";
+import { localized } from "./summary.js";
+const Id = z.string().min(1).max(100);
+const Version = z.string().min(1).max(100);
+const Hash = z.string().min(1).max(200);
+/** Entries per page of the paged lists (the tool caps a bare list at 50). */
+const PAGE = 50;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const OTHER_ORG = "This plugin belongs to another org; use the admin console.";
+const LOCKED = "This plugin is on for every org (or shipped with the platform) and cannot be switched off in one org.";
+/** The confirm value of switching off a plugin with nothing installed in the org. */
+const NOTHING_INSTALLED = "nothing-installed";
+export const NEEDS_INPUT = "This plugin needs configuration a person must enter; ask them to enable it on the 插件 page.";
+/** An org's view of a plugin, as the list shows it. */
+const brief = (i) => ({
+    id: i.id,
+    name: i.name,
+    displayName: i.displayName,
+    description: i.description,
+    scope: i.scope,
+    state: i.state,
+    switchable: i.switchable,
+    builtin: i.builtin,
+    notDeployed: i.notDeployed,
+    latestVersion: i.latestVersion,
+    installedVersion: i.installed?.version ?? null,
+    componentCounts: i.componentCounts,
+    owner: i.owner,
+    request: i.request,
+});
+const hasConfigFields = (schema) => {
+    const props = schema?.properties;
+    return typeof props === "object" && props !== null && Object.keys(props).length > 0;
+};
+/**
+ * Whether switching the plugin on needs input a person enters (the web's install wizard, the
+ * web's `needsInput`): an org config still missing (`needs_config`), connector templates, or the
+ * org config form of its extension while that extension is off in the org.
+ */
+function needsInput(item, extensions) {
+    if (item.state === "needs_config")
+        return true;
+    if (item.installed !== null)
+        return false;
+    if (item.componentCounts.connectorTemplates > 0)
+        return true;
+    if (item.componentCounts.extension === 0)
+        return false;
+    const own = extensions.find((e) => e.catalogItem?.itemId === item.id);
+    return own !== undefined && !own.enabled && hasConfigFields(own.orgConfigSchema);
+}
+/**
+ * Plugin operations of the `Platform` tool (spec §7): the org's view (list, get, switch on or off)
+ * and the super admin's platform view (list, get, update with its preview). Every platform result
+ * goes through {@link redactOrgs}: other orgs only as counts (spec §6.1).
+ */
+let PluginsOperations = class PluginsOperations {
+    registry;
+    orgCatalog;
+    catalog;
+    updater;
+    installer;
+    extensions;
+    kdb;
+    constructor(registry, orgCatalog, catalog, updater, installer, extensions, kdb) {
+        this.registry = registry;
+        this.orgCatalog = orgCatalog;
+        this.catalog = catalog;
+        this.updater = updater;
+        this.installer = installer;
+        this.extensions = extensions;
+        this.kdb = kdb;
+    }
+    /**
+     * Refuses a super-admin operation on an item another org owns: its results would describe that
+     * org's private plugin in this org's log (spec §6.1). Platform items and the org's own pass.
+     */
+    async assertNotOtherOrgs(itemId, orgId) {
+        if (!UUID_RE.test(itemId))
+            return;
+        const row = await this.kdb.db
+            .selectFrom("catalog_items")
+            .select("owner_org_id")
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        if (row?.owner_org_id != null && row.owner_org_id !== orgId)
+            throw new ToolError(OTHER_ORG);
+    }
+    /** How many live catalog items other orgs own (left out of the platform list). */
+    async otherOrgItems(orgId) {
+        const r = await this.kdb.db
+            .selectFrom("catalog_items")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("deleted_at", "is", null)
+            .where("owner_org_id", "is not", null)
+            .where("owner_org_id", "!=", orgId)
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "plugins.list",
+                description: "List the plugins this org can see, with their state here (on, off, needs_config, unavailable, not_offered), whether an org admin can switch them, and the org's pending request. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog"],
+                confirm: "read",
+                run: async (input, ctx) => {
+                    const all = await this.orgCatalog.list(ctx.orgId, ctx.actorAccountId);
+                    return pageOf(all.map(brief), startOf(input.cursor), PAGE);
+                },
+            }),
+            defineOperation({
+                id: "plugins.get",
+                description: "Read one plugin as this org sees it: its state, extension, connector templates (presets only, never credentials), dependencies, skills and agent templates.",
+                input: z.object({ itemId: Id }).strict(),
+                example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId"],
+                confirm: "read",
+                errors: [
+                    { code: "catalog.item_not_found", next: "Check the plugin id with plugins.list." },
+                ],
+                run: async (input, ctx) => asToolError(async () => {
+                    const d = await this.orgCatalog.detail(ctx.orgId, ctx.actorAccountId, input.itemId);
+                    return { ...d, item: brief(d.item) };
+                }),
+            }),
+            defineOperation({
+                id: "plugins.disable-preview",
+                description: "Preview switching a plugin off in this org (org admins): what it would remove and which agents use it, and the confirm value plugins.set-enabled needs to switch it off. Show the preview to the person before switching off.",
+                input: z.object({ itemId: Id }).strict(),
+                example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
+                // the web previews through the switch route itself (no confirm); writes nothing here
+                authz: { orgAction: "org.extensions.manage" },
+                mirrors: [],
+                confirm: "read",
+                errors: [
+                    { code: "catalog.item_not_found", next: "Check the plugin id with plugins.list." },
+                ],
+                run: async (input, ctx) => asToolError(async () => {
+                    const d = await this.orgCatalog.detail(ctx.orgId, ctx.actorAccountId, input.itemId);
+                    if (!d.item.switchable)
+                        throw new ToolError(LOCKED);
+                    const live = d.item.installed;
+                    if (live === null) {
+                        return {
+                            preview: null,
+                            confirm: NOTHING_INSTALLED,
+                            next: "Nothing is installed in the org, so switching off removes nothing; pass this confirm value.",
+                        };
+                    }
+                    const preview = await this.installer.previewUninstall(ctx.orgId, live.pluginInstallId);
+                    return { preview, confirm: uninstallPreviewHash(preview) };
+                }),
+            }),
+            defineOperation({
+                id: "plugins.set-enabled",
+                description: "Switch a plugin on or off in this org. Switching on installs it; a plugin whose enabling needs configuration a person enters (connector credentials, extension config) is refused, so point the person to the 插件 page. Switching off removes what the plugin brought and needs confirm: the value plugins.disable-preview returned with the preview the person saw.",
+                input: z.discriminatedUnion("enabled", [
+                    z.object({ itemId: Id, enabled: z.literal(true) }).strict(),
+                    z.object({ itemId: Id, enabled: z.literal(false), confirm: Hash }).strict(),
+                ]),
+                example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c", enabled: true },
+                // the route needs catalog.read; setSwitch requires an org admin (any of skills.manage,
+                // connectors.manage, org.extensions.manage, all the admin role)
+                authz: { orgAction: "org.extensions.manage" },
+                authzNote: "service-enforced",
+                mirrors: ["PUT /api/v1/orgs/:orgId/catalog/:itemId/switch"],
+                confirm: "org",
+                errors: [
+                    {
+                        code: "plugin.switch_stale",
+                        next: "The uninstall preview changed: call plugins.disable-preview again, show it, and call again with the new confirm value.",
+                    },
+                    {
+                        code: "plugin.scope_locked",
+                        next: "The plugin is on for every org and cannot be switched off in one org.",
+                    },
+                    {
+                        code: "plugin.disabled",
+                        next: "The super admin stopped this plugin on the platform; ask them.",
+                    },
+                    {
+                        code: "catalog.approval_required",
+                        next: "The plugin is not offered to this org: create an access request with requests.create.",
+                    },
+                    {
+                        code: "plugin.skill_conflict",
+                        next: "An org skill has the name of one of the plugin's skills; the person resolves it on the web.",
+                    },
+                ],
+                summary: async (i, ctx) => {
+                    const [item] = await this.orgCatalog.list(ctx.orgId, ctx.actorAccountId, i.itemId);
+                    if (item === undefined)
+                        throw new Error("no such plugin");
+                    const n = localized(item.displayName, item.name);
+                    if (i.enabled) {
+                        return { zh: `在本组织启用插件「${n.zh}」`, en: `Enable plugin "${n.en}" in the org` };
+                    }
+                    const live = item.installed;
+                    if (live === null) {
+                        return {
+                            zh: `在本组织停用插件「${n.zh}」（本组织未安装任何内容）`,
+                            en: `Disable plugin "${n.en}" in the org (nothing is installed here)`,
+                        };
+                    }
+                    // the preview the confirm value binds: what goes, and the agents that lose it
+                    const p = await this.installer.previewUninstall(ctx.orgId, live.pluginInstallId);
+                    return {
+                        zh: `在本组织停用插件「${n.zh}」：移除 ${p.components.length} 个组件，${p.agents.length} 个智能体在用`,
+                        en: `Disable plugin "${n.en}" in the org: removes ${p.components.length} components; ${p.agents.length} agents use it`,
+                    };
+                },
+                run: async (input, ctx) => asToolError(async () => {
+                    if (input.enabled) {
+                        const [item] = await this.orgCatalog.list(ctx.orgId, ctx.actorAccountId, input.itemId);
+                        if (item && needsInput(item, await this.extensions.list(ctx.orgId))) {
+                            throw new ToolError(NEEDS_INPUT);
+                        }
+                    }
+                    const r = await this.orgCatalog.setSwitch(ctx.orgId, ctx.actorAccountId, input.itemId, input.enabled ? { enabled: true } : { enabled: false, confirm: input.confirm }, undefined, viaAgent("plugins.set-enabled", ctx));
+                    if (r.kind === "done")
+                        return { item: brief(r.item) };
+                    // unreachable: confirm is required when switching off
+                    return { preview: r.preview, confirm: r.confirm };
+                }),
+            }),
+            defineOperation({
+                id: "plugins.platform-list",
+                description: "List the platform's plugins and this org's own (super admin): scope, disabled, versions, pending confirmation and how many orgs use it. Plugins other orgs own are only counted (otherOrgItems); orgs are given as counts. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { superAdmin: true },
+                mirrors: ["GET /api/v1/admin/catalog/items"],
+                confirm: "read",
+                run: async (input, ctx) => {
+                    const p = await this.catalog.page({ limit: PAGE, offset: startOf(input.cursor) });
+                    return redactOrgs({
+                        items: p.items.filter((i) => i.owner.kind !== "org" || i.owner.orgId === ctx.orgId),
+                        otherOrgItems: await this.otherOrgItems(ctx.orgId),
+                        next: p.nextOffset === null ? null : String(p.nextOffset),
+                    });
+                },
+            }),
+            defineOperation({
+                id: "plugins.platform-get",
+                description: "Read one platform catalog plugin (super admin): the item, its platform version and every version with its source. Orgs are given as counts only.",
+                input: z.object({ itemId: Id }).strict(),
+                example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
+                authz: { superAdmin: true },
+                mirrors: ["GET /api/v1/admin/catalog/items/:id"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "Check the plugin id with plugins.platform-list.",
+                    },
+                ],
+                run: async (input, ctx) => asToolError(async () => {
+                    await this.assertNotOtherOrgs(input.itemId, ctx.orgId);
+                    const d = await this.catalog.get(input.itemId);
+                    return redactOrgs({
+                        item: d.item,
+                        versions: d.versions.map((v) => ({
+                            version: v.version,
+                            source: v.source,
+                            sourceRef: v.sourceRef,
+                            sourceFormat: v.sourceFormat,
+                            importedAt: v.importedAt,
+                            ...(v.version === d.item.platformVersion && { manifest: v.manifest }),
+                        })),
+                    });
+                }),
+            }),
+            defineOperation({
+                id: "plugins.update-preview",
+                description: "Preview updating a platform plugin to another imported version (super admin): every component's change, the extension step and the org connectors it touches, with the diffHash plugins.update takes. Orgs are given as counts only; the admin console shows which.",
+                input: z.object({ itemId: Id, version: Version }).strict(),
+                example: { itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c", version: "1.2.0" },
+                authz: { superAdmin: true },
+                mirrors: ["POST /api/v1/admin/catalog/items/:id/update/preview"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "Check the plugin id and its versions with plugins.platform-get.",
+                    },
+                ],
+                run: async (input, ctx) => asToolError(async () => {
+                    await this.assertNotOtherOrgs(input.itemId, ctx.orgId);
+                    return redactOrgs(await this.updater.preview(input.itemId, input.version));
+                }),
+            }),
+            defineOperation({
+                id: "plugins.update",
+                description: "Update a platform plugin to the version previewed (super admin), for every org at once: pass the version and the diffHash plugins.update-preview returned. A preview that is out of date is refused; preview again.",
+                input: z.object({ itemId: Id, version: Version, diffHash: Hash }).strict(),
+                example: {
+                    itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c",
+                    version: "1.2.0",
+                    diffHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                },
+                authz: { superAdmin: true },
+                mirrors: ["PUT /api/v1/admin/catalog/items/:id/update"],
+                confirm: "platform",
+                errors: [
+                    {
+                        code: "plugin.upgrade_stale",
+                        next: "Call plugins.update-preview again and use its new diffHash.",
+                    },
+                    {
+                        code: "plugin.install_in_progress",
+                        next: "Another update of this plugin is running; try again in a minute.",
+                    },
+                ],
+                summary: async (i, ctx) => {
+                    await this.assertNotOtherOrgs(i.itemId, ctx.orgId);
+                    const [{ item }, p] = await Promise.all([
+                        this.catalog.get(i.itemId),
+                        this.updater.preview(i.itemId, i.version),
+                    ]);
+                    const n = localized(item.displayName, item.name);
+                    const count = (...changes) => p.components.filter((c) => changes.includes(c.change)).length;
+                    const changed = count("upgrade", "downgrade");
+                    const added = count("added");
+                    const removed = count("removed");
+                    // one version for every org: the orgs it is on in, as a count (spec §6.1)
+                    const orgs = item.enabledOrgs;
+                    return {
+                        zh: `把平台插件「${n.zh}」从 ${p.from ?? "无"} 更新到 ${p.to}：组件 ${changed} 个更新、${added} 个新增、${removed} 个移除，影响 ${orgs} 个组织`,
+                        en: `Update platform plugin "${n.en}" from ${p.from ?? "none"} to ${p.to}: components ${changed} updated, ${added} added, ${removed} removed; ${orgs} orgs affected`,
+                    };
+                },
+                run: async (input, ctx) => asToolError(async () => {
+                    await this.assertNotOtherOrgs(input.itemId, ctx.orgId);
+                    return redactOrgs(await this.updater.update(ctx.actorAccountId, input.itemId, { version: input.version, diffHash: input.diffHash }, { auditDetail: viaAgent("plugins.update", ctx) }));
+                }),
+            }),
+        ]);
+    }
+};
+PluginsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(OrgCatalogService)),
+    __param(2, Inject(CatalogService)),
+    __param(3, Inject(PlatformPluginUpdater)),
+    __param(4, Inject(PluginInstaller)),
+    __param(5, Inject(OrgExtensionConfigs)),
+    __param(6, Inject(KernelDb))
+], PluginsOperations);
+export { PluginsOperations };

package/dist/platform/ops/requests.ops.d.ts

@@ -0,0 +1,14 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { CatalogRequestsService } from "../../catalog/requests.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Request operations of the `Platform` tool (spec §7): a member asks the org admins to switch a
+ * plugin on, an org admin asks the super admin for access to a plugin or for an import from a
+ * marketplace. Deciding a request is human-only (spec §6.4) and not offered.
+ */
+export declare class RequestsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly requests;
+    constructor(registry: PlatformOperations, requests: CatalogRequestsService);
+    onModuleInit(): void;
+}