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

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

@@ -0,0 +1,191 @@
+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 { z } from "zod";
+import { CatalogItemPathParams, CatalogMarketplaceRequestBody, CatalogRequestBody, CatalogRequestsListQuery, } from "../../catalog/org-catalog.schemas.js";
+import { CatalogRequestsService } from "../../catalog/requests.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { viaAgent } from "./errors.js";
+import { Cursor, pageOf, startOf } from "./paging.js";
+/** A request as the requester reads it (no org name: it is this org's). */
+const view = (r) => ({
+    id: r.id,
+    kind: r.kind,
+    status: r.status,
+    item: r.item,
+    entry: r.entry,
+    agent: r.agent,
+    note: r.note,
+    reason: r.reason,
+    decidedAt: r.decidedAt,
+    createdAt: r.createdAt,
+});
+/** A platform request as the super admin's list shows it: a compact row (the inbox's summary). */
+const platformRow = (r) => ({
+    id: r.id,
+    name: r.item?.name ?? r.entry?.name ?? r.kind,
+    state: r.status,
+    kind: r.kind,
+    org: r.orgName,
+    createdAt: r.createdAt,
+});
+/** A member's pending request as the org admins' list shows it: a compact row (the inbox's). */
+const pendingRow = (r) => ({
+    id: r.id,
+    name: r.item?.name ?? r.entry?.name ?? r.agent?.name ?? r.kind,
+    state: r.status,
+    kind: r.kind,
+    requestedBy: r.requestedByName,
+    note: r.note,
+    next: "Decide it on the web, in the inbox; agents never decide requests.",
+});
+/**
+ * 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.
+ */
+let RequestsOperations = class RequestsOperations {
+    registry;
+    requests;
+    constructor(registry, requests) {
+        this.registry = registry;
+        this.requests = requests;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "requests.list-mine",
+                description: "List the requests you made in this org, pending and decided, newest first: what was asked (a plugin, a marketplace entry, an agent's connectors), the status and a rejection's reason. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { orgAction: "catalog.request" },
+                mirrors: [],
+                confirm: "read",
+                run: async (input, ctx) => {
+                    const mine = await this.requests.listForRequester(ctx.orgId, ctx.actorAccountId);
+                    return pageOf(mine.map(view), startOf(input.cursor), 50);
+                },
+            }),
+            defineOperation({
+                id: "requests.create",
+                description: 'Ask for a plugin: kind "enable" asks the org admins to switch on a plugin that is off in this org (members and up); kind "access" asks the super admin to offer this org a plugin it sees as not_offered (org admins). Take the plugin id and state from plugins.list. An optional note says why.',
+                input: z
+                    .object({ itemId: CatalogItemPathParams.shape.itemId.max(100) })
+                    .extend(CatalogRequestBody.shape)
+                    .strict(),
+                example: {
+                    itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c",
+                    kind: "enable",
+                    note: "Our team needs it for the weekly report.",
+                },
+                authz: { orgAction: "catalog.request" },
+                mirrors: ["POST /api/v1/orgs/:orgId/catalog/:itemId/requests"],
+                confirm: "personal",
+                errors: [
+                    {
+                        code: "catalog.request_pending",
+                        next: "The org already has a pending request of this kind for the plugin; nothing to do but wait.",
+                    },
+                    {
+                        code: "catalog.request_invalid",
+                        next: 'The plugin\'s state does not fit the kind: "enable" needs state off, "access" needs not_offered. Check plugins.list.',
+                    },
+                    {
+                        code: "forbidden",
+                        next: 'Only org admins can ask for access; ask an org admin, or use kind "enable".',
+                    },
+                ],
+                summary: (i) => i.kind === "enable"
+                    ? {
+                        zh: `申请在本组织启用插件 ${i.itemId}`,
+                        en: `Request that plugin ${i.itemId} be enabled in the org`,
+                    }
+                    : {
+                        zh: `向超级管理员申请插件 ${i.itemId} 的使用权`,
+                        en: `Request access to plugin ${i.itemId} from the super admin`,
+                    },
+                run: async (input, ctx) => ({
+                    request: view(await this.requests.requestItem(ctx.orgId, ctx.actorAccountId, input.itemId, { kind: input.kind, ...(input.note !== undefined && { note: input.note }) }, { auditDetail: viaAgent("requests.create", ctx) })),
+                }),
+            }),
+            defineOperation({
+                id: "requests.create-import",
+                description: "Ask the super admin to import a plugin from a marketplace into the platform catalog (org admins, when the platform lets orgs browse): the marketplaceId, name and version from marketplaces.entries, and an optional note.",
+                input: CatalogMarketplaceRequestBody,
+                example: { marketplaceId: "official", name: "github", version: "1.4.0" },
+                authz: { orgAction: "catalog.decide" },
+                mirrors: ["POST /api/v1/orgs/:orgId/marketplace-requests"],
+                confirm: "org",
+                errors: [
+                    {
+                        code: "catalog.marketplace_browse_disabled",
+                        next: "The platform does not let orgs request imports; ask the super admin directly.",
+                    },
+                    {
+                        code: "catalog.request_invalid",
+                        next: 'The plugin is in the catalog already: use requests.create with kind "access" or "enable".',
+                    },
+                    {
+                        code: "catalog.request_pending",
+                        next: "A request for this entry is pending already; wait for the super admin.",
+                    },
+                ],
+                summary: (i) => ({
+                    zh: `申请从市场导入插件 ${i.name} ${i.version}`,
+                    en: `Request the import of plugin ${i.name} ${i.version} from a marketplace`,
+                }),
+                run: async (input, ctx) => ({
+                    request: view(await this.requests.requestImport(ctx.orgId, ctx.actorAccountId, {
+                        marketplaceId: input.marketplaceId,
+                        name: input.name,
+                        version: input.version,
+                        ...(input.note !== undefined && { note: input.note }),
+                    }, { auditDetail: viaAgent("requests.create-import", ctx) })),
+                }),
+            }),
+            defineOperation({
+                id: "requests.pending",
+                description: "List the requests members sent this org's admins that wait for a decision (org admins), as the inbox shows them, newest first: kind enable (switch a plugin on) or connector_setup (set up an agent's connectors), what it is about (the plugin or the agent), who asked and their note. Deciding them is done on the web. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { orgAction: "catalog.decide" },
+                mirrors: [],
+                confirm: "read",
+                run: async (input, ctx) => {
+                    const all = await this.requests.listForOrgAdmin(ctx.orgId, ctx.actorAccountId);
+                    return pageOf(all.map(pendingRow), startOf(input.cursor), 50);
+                },
+            }),
+            defineOperation({
+                id: "requests.platform-list",
+                description: "List the requests orgs sent the super admin (super admin): access to a plugin and imports from a marketplace, one compact row each (what, status, kind, the requesting org, when), newest first; pending by default, or filter by status. Deciding them is done on the web. Pages by 50: pass the returned next as params.cursor.",
+                input: z
+                    .object({ status: CatalogRequestsListQuery.shape.status, cursor: Cursor.optional() })
+                    .strict(),
+                example: {},
+                authz: { superAdmin: true },
+                mirrors: ["GET /api/v1/admin/catalog/requests"],
+                extras: ["cursor"],
+                confirm: "read",
+                run: async (input) => {
+                    const all = await this.requests.listDeployment(input.status !== undefined ? { status: input.status } : {});
+                    return pageOf(all.map(platformRow), startOf(input.cursor), 50);
+                },
+            }),
+        ]);
+    }
+};
+RequestsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(CatalogRequestsService))
+], RequestsOperations);
+export { RequestsOperations };

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

@@ -0,0 +1,4 @@
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import type { OrgRole } from "../../orgs/roles.js";
+/** The account's role in the org, read now; null when it is not a member. */
+export declare function roleOf(db: KernelSchemaDb, orgId: string, accountId: string): Promise<OrgRole | null>;

package/dist/platform/ops/role.js

@@ -0,0 +1,10 @@
+/** The account's role in the org, read now; null when it is not a member. */
+export async function roleOf(db, orgId, accountId) {
+    const m = await db
+        .selectFrom("memberships")
+        .select("role")
+        .where("org_id", "=", orgId)
+        .where("account_id", "=", accountId)
+        .executeTakeFirst();
+    return m?.role ?? null;
+}

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

@@ -0,0 +1,24 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { SetupChecksService } from "../../setup/setup-checks.service.js";
+import { SetupGuidesService } from "../../setup/setup-guides.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Setup guide operations of the `Platform` tool (spec 2026-11-09-setup-guides-v2-design.md §12),
+ * the `setup` domain: the guides a person may see, one guide rendered as Markdown, the cached check
+ * states of a guide and running one check. All are reads (a check never writes anywhere; its cost
+ * is bounded by the cache, the cooldown and the org's concurrency cap) and use the routes'
+ * services, so a guide carries no secret (§6.3) and check results only the fixed, redacted fields.
+ * Entering a secret, OAuth consent and the guide ack stay with the person on the web (`human-only`
+ * and `secret` exclusions); no setup operation takes a value.
+ */
+export declare class SetupOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly checks;
+    private readonly guides;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, checks: SetupChecksService, guides: SetupGuidesService, kdb: KernelDb);
+    /** The actor as the routes see a caller: the org, their role there now and their account. */
+    private caller;
+    onModuleInit(): void;
+}

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

@@ -0,0 +1,212 @@
+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 { CatalogGuidePathParams, CatalogGuideQuery } from "../../catalog/org-catalog.schemas.js";
+import { ApiError } from "../../errors.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { SetupCheckPathParams, SetupCheckRunBody, SetupChecksQuery, SetupGuidePathParams, } from "../../setup/setup-checks.schemas.js";
+import { SetupChecksService } from "../../setup/setup-checks.service.js";
+import { SetupGuidesQuery } from "../../setup/setup-guides.schemas.js";
+import { SetupGuidesService } from "../../setup/setup-guides.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { roleOf } from "./role.js";
+const ITEM = "00000000-0000-4000-8000-000000000000";
+const CONNECTION = "00000000-0000-4000-8000-000000000001";
+/**
+ * Setup guide operations of the `Platform` tool (spec 2026-11-09-setup-guides-v2-design.md §12),
+ * the `setup` domain: the guides a person may see, one guide rendered as Markdown, the cached check
+ * states of a guide and running one check. All are reads (a check never writes anywhere; its cost
+ * is bounded by the cache, the cooldown and the org's concurrency cap) and use the routes'
+ * services, so a guide carries no secret (§6.3) and check results only the fixed, redacted fields.
+ * Entering a secret, OAuth consent and the guide ack stay with the person on the web (`human-only`
+ * and `secret` exclusions); no setup operation takes a value.
+ */
+let SetupOperations = class SetupOperations {
+    registry;
+    checks;
+    guides;
+    kdb;
+    constructor(registry, checks, guides, kdb) {
+        this.registry = registry;
+        this.checks = checks;
+        this.guides = guides;
+        this.kdb = kdb;
+    }
+    /** The actor as the routes see a caller: the org, their role there now and their account. */
+    async caller(ctx) {
+        const role = await roleOf(this.kdb.db, ctx.orgId, ctx.actorAccountId);
+        if (role === null)
+            throw new ApiError("forbidden", "Insufficient organization role");
+        return { orgId: ctx.orgId, role, accountId: ctx.actorAccountId };
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "setup.guides",
+                description: "List the plugin setup guides this person may help with in the org: per guide its targets (channel connections, connectors made from a template, templates switched on without a connector yet), whether the guide changed since a target was set up (drift), a count of the cached check states and the web page where the person does the setup. Org admins get the admin guides; members get the guides for connecting their own account. Read a guide with setup.read.",
+                input: SetupGuidesQuery,
+                example: {},
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/setup-guides"],
+                confirm: "read",
+                run: async (input, ctx) => ({
+                    guides: await this.guides.list(await this.caller(ctx), input),
+                }),
+            }),
+            defineOperation({
+                id: "setup.read",
+                description: "Read one plugin setup guide rendered for a target as a Markdown document: the steps, the app manifest and URLs to paste at the third-party platform, and the checks as '- [check <id>] <label>' lines (run them with setup.check), with the modes, the variables that have no value yet and why, and the web page of the target. Explain the step the person is on. Secrets are never in the guide: ask the person to paste each token or secret into its field on the returned webPath, never into the conversation.",
+                input: CatalogGuidePathParams.extend(CatalogGuideQuery.shape).strict(),
+                example: { itemId: ITEM, guideId: "slack-app", connectionId: CONNECTION },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; list the guides with setup.guides.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; list the guides with setup.guides.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Pass a mode and audience the guide has (setup.guides lists the audience) and the target of its place: connectionId for a channel guide, connectorId for a connector template guide.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins read the admin guides; members read the member section of a connector template guide (audience member).",
+                        },
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, ...q } = input;
+                    return { guide: await this.guides.read(await this.caller(ctx), itemId, guideId, q) };
+                },
+            }),
+            defineOperation({
+                id: "setup.status",
+                description: "Read the cached state of every check of a plugin's setup guide for one target (a channel connection or a connector made from a template), by check id: ok, failing, unknown, running or not_run, with the reason and fix to show the person. Runs nothing; run a check with setup.check.",
+                input: SetupGuidePathParams.extend(SetupChecksQuery.shape).strict(),
+                example: { itemId: ITEM, guideId: "slack-app", connectionId: CONNECTION },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; check the item id on the plugin's page.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; read the guide id from the connection or connector page.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Checks need a saved target: pass connectionId for a channel guide or connectorId for a connector template guide, and a mode and audience the guide has.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins run the admin checks of a guide; members run the member checks (audience member).",
+                        },
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, ...q } = input;
+                    return { results: await this.checks.states(await this.caller(ctx), itemId, guideId, q) };
+                },
+            }),
+            defineOperation({
+                id: "setup.check",
+                description: "Run one check of a plugin's setup guide for one target (a channel connection or a connector made from a template) and return its state: ok, failing (with a reason and a fix to explain), unknown, or running (try again in a moment). A fresh cached result is returned as is; force reruns it, at most once per 10 seconds per check and target. A check only reads; run it after the person says they finished a step.",
+                input: SetupCheckPathParams.extend(SetupCheckRunBody.shape).strict(),
+                example: {
+                    itemId: ITEM,
+                    guideId: "slack-app",
+                    checkId: "bot-token",
+                    connectionId: CONNECTION,
+                },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["POST /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks/:checkId/run"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; check the item id on the plugin's page.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; read the guide id from the connection or connector page.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Checks need a saved target: pass connectionId for a channel guide or connectorId for a connector template guide, and a mode and audience the guide has.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins run the admin checks of a guide; members run the member checks (audience member).",
+                        },
+                    },
+                    {
+                        code: "catalog.check_not_found",
+                        next: "That check is not in the guide for this mode and audience; read the check ids with setup.status.",
+                    },
+                    {
+                        code: "rate_limited",
+                        next: "This person ran 30 checks in the last minute; wait a minute before running another, and read the cached states with setup.status meanwhile.",
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, checkId, ...body } = input;
+                    return {
+                        result: await this.checks.run(await this.caller(ctx), itemId, guideId, checkId, body),
+                    };
+                },
+            }),
+        ]);
+    }
+};
+SetupOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(SetupChecksService)),
+    __param(2, Inject(SetupGuidesService)),
+    __param(3, Inject(KernelDb))
+], SetupOperations);
+export { SetupOperations };

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

@@ -0,0 +1,17 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { OwnedItems } from "../../catalog/owned-items.js";
+import { SkillsService } from "../../skills/skills.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Skill library operations of the `Platform` tool (spec §7). The skill body can be long; `get`
+ * returns it whole because reading it is the point of the call.
+ */
+export declare class SkillsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly skills;
+    private readonly owned;
+    constructor(registry: PlatformOperations, skills: SkillsService, owned: OwnedItems);
+    /** The skill's name for a card summary; its id when it cannot be read. */
+    private skillName;
+    onModuleInit(): void;
+}

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

@@ -0,0 +1,160 @@
+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 { z } from "zod";
+import { OwnedItems } from "../../catalog/owned-items.js";
+import { SkillIdParams, SkillPathParams, SkillShareableSchema, } from "../../skills/skills.schemas.js";
+import { SkillsService } from "../../skills/skills.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { precheckBy, viaAgent } from "./errors.js";
+import { named, orElse } from "./summary.js";
+const NoInput = z.object({}).strict();
+const SkillId = z.object({ skillId: SkillPathParams.shape.id.max(100) }).strict();
+const OwnedSkillId = z.object({ skillId: SkillIdParams.shape.id }).strict();
+/**
+ * Skill library operations of the `Platform` tool (spec §7). The skill body can be long; `get`
+ * returns it whole because reading it is the point of the call.
+ */
+let SkillsOperations = class SkillsOperations {
+    registry;
+    skills;
+    owned;
+    constructor(registry, skills, owned) {
+        this.registry = registry;
+        this.skills = skills;
+        this.owned = owned;
+    }
+    /** The skill's name for a card summary; its id when it cannot be read. */
+    skillName(orgId, skillId) {
+        return orElse(async () => named((await this.skills.get(orgId, skillId)).name), skillId);
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "skills.list",
+                description: "List the skills the org can use, org skills and platform skills switched on in it. Each entry has an id, name, description, current version and where it came from.",
+                input: NoInput,
+                example: {},
+                authz: { orgAction: "skills.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/skills"],
+                confirm: "read",
+                run: async (_input, ctx) => ({ skills: await this.skills.list(ctx.orgId) }),
+            }),
+            defineOperation({
+                id: "skills.get",
+                description: "Read one skill: its description, versions, file list and the current SKILL.md body. Takes the skill id from skills.list.",
+                input: SkillId,
+                example: { skillId: "0b9f2c4e-1d3a-4c55-9e0a-7a2f6d1c8b11" },
+                authz: { orgAction: "skills.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/skills/:id"],
+                renames: { skillId: "id" },
+                confirm: "read",
+                run: async (input, ctx) => this.skills.get(ctx.orgId, input.skillId),
+            }),
+            defineOperation({
+                id: "skills.set-shareable",
+                description: "Set whether an org skill may be shared with other orgs. Only the org's own skills can be changed; a skill that came from a platform plugin cannot.",
+                input: OwnedSkillId.extend({ shareable: SkillShareableSchema.shape.shareable }).strict(),
+                example: { skillId: "0b9f2c4e-1d3a-4c55-9e0a-7a2f6d1c8b11", shareable: true },
+                authz: { orgAction: "skills.manage" },
+                mirrors: ["PUT /api/v1/orgs/:orgId/skills/:id/shareable"],
+                renames: { skillId: "id" },
+                confirm: "org",
+                errors: [
+                    {
+                        code: "skill.not_found",
+                        next: "Check the skill id with skills.list; only the org's own skills can be changed or deleted here.",
+                    },
+                    {
+                        code: "catalog.not_owned",
+                        next: "Only a skill the org created can be shared; a platform skill or a copy of another owner's is not the org's to share.",
+                    },
+                ],
+                precheck: (i, ctx) => precheckBy(() => this.owned.previewSkillDelete(ctx.orgId, i.skillId)),
+                summary: async (i, ctx) => {
+                    const n = await this.skillName(ctx.orgId, i.skillId);
+                    return i.shareable
+                        ? {
+                            zh: `允许把组织技能「${n}」共享给其他组织`,
+                            en: `Allow org skill "${n}" to be shared with other orgs`,
+                        }
+                        : {
+                            zh: `不再把组织技能「${n}」共享给其他组织`,
+                            en: `Stop sharing org skill "${n}" with other orgs`,
+                        };
+                },
+                run: async (input, ctx) => {
+                    await this.owned.setShareable(ctx.orgId, ctx.actorAccountId, { kind: "skill", id: input.skillId }, input.shareable, { auditDetail: viaAgent("skills.set-shareable", ctx) });
+                    return { id: input.skillId, shareable: input.shareable };
+                },
+            }),
+            defineOperation({
+                id: "skills.delete-preview",
+                description: "Preview deleting an org skill (org admins): whether it is removed or handed to the platform because another org uses it, and which of the org's agents lose it. Show it to the person before skills.delete.",
+                input: OwnedSkillId,
+                example: { skillId: "0b9f2c4e-1d3a-4c55-9e0a-7a2f6d1c8b11" },
+                authz: { orgAction: "skills.manage" },
+                mirrors: ["GET /api/v1/orgs/:orgId/skills/:id/delete-preview"],
+                renames: { skillId: "id" },
+                confirm: "read",
+                errors: [
+                    {
+                        code: "skill.not_found",
+                        next: "Check the skill id with skills.list; only the org's own skills can be changed or deleted here.",
+                    },
+                ],
+                run: async (input, ctx) => ({
+                    preview: await this.owned.previewSkillDelete(ctx.orgId, input.skillId),
+                }),
+            }),
+            defineOperation({
+                id: "skills.delete",
+                description: "Delete an org skill. Agents of the org that use it lose it; a skill another org uses is handed to the platform instead of removed. Read skills.delete-preview first and show it to the person.",
+                input: OwnedSkillId,
+                example: { skillId: "0b9f2c4e-1d3a-4c55-9e0a-7a2f6d1c8b11" },
+                authz: { orgAction: "skills.manage" },
+                mirrors: ["DELETE /api/v1/orgs/:orgId/skills/:id"],
+                renames: { skillId: "id" },
+                confirm: "org",
+                errors: [
+                    {
+                        code: "skill.not_found",
+                        next: "Check the skill id with skills.list; only the org's own skills can be changed or deleted here.",
+                    },
+                ],
+                precheck: (i, ctx) => precheckBy(() => this.owned.previewSkillDelete(ctx.orgId, i.skillId)),
+                summary: async (i, ctx) => {
+                    const n = await this.skillName(ctx.orgId, i.skillId);
+                    const p = await orElse(() => this.owned.previewSkillDelete(ctx.orgId, i.skillId), null);
+                    const agents = p?.agents.length ?? 0;
+                    const handed = p?.outcome === "transferred";
+                    return {
+                        zh: `删除组织技能「${n}」：${agents} 个智能体将失去它${handed ? "；其他组织在用，将转为平台技能" : ""}`,
+                        en: `Delete org skill "${n}": ${agents} agents lose it${handed ? "; another org uses it, so it becomes a platform skill" : ""}`,
+                    };
+                },
+                run: async (input, ctx) => ({
+                    id: input.skillId,
+                    outcome: await this.owned.deleteSkill(ctx.orgId, ctx.actorAccountId, input.skillId, {
+                        auditDetail: viaAgent("skills.delete", ctx),
+                    }),
+                }),
+            }),
+        ]);
+    }
+};
+SkillsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(SkillsService)),
+    __param(2, Inject(OwnedItems))
+], SkillsOperations);
+export { SkillsOperations };

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

@@ -0,0 +1,10 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+/** A name as a card summary quotes it: clipped to {@link NAME_MAX}. */
+export declare const named: (s: string) => string;
+/** A display name in both languages, clipped; `fallback` (the plain name) for a missing one. */
+export declare const localized: (n: LocalizedName | null | undefined, fallback: string) => {
+    zh: string;
+    en: string;
+};
+/** The value of `read`, or `fallback` when the read throws (a summary never fails on a name). */
+export declare function orElse<T>(read: () => Promise<T>, fallback: T): Promise<T>;

package/dist/platform/ops/summary.js

@@ -0,0 +1,18 @@
+/** Longest name quoted in a card summary (a name is set by people, and by agents through tools). */
+const NAME_MAX = 80;
+/** A name as a card summary quotes it: clipped to {@link NAME_MAX}. */
+export const named = (s) => (s.length > NAME_MAX ? `${s.slice(0, NAME_MAX)}…` : s);
+/** A display name in both languages, clipped; `fallback` (the plain name) for a missing one. */
+export const localized = (n, fallback) => ({
+    zh: named(n?.zh ?? fallback),
+    en: named(n?.en ?? fallback),
+});
+/** The value of `read`, or `fallback` when the read throws (a summary never fails on a name). */
+export async function orElse(read, fallback) {
+    try {
+        return await read();
+    }
+    catch {
+        return fallback;
+    }
+}