@capybara-hq/kernel 0.1.0-rc.6 → 0.1.0-rc.7

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

@@ -0,0 +1,109 @@
+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 { PreviewerRegistry } from "../../files/previewers.js";
+import { FilePreviewersOrderBody } from "../../files/previewers.schemas.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { viaAgent } from "./errors.js";
+import { named } from "./summary.js";
+const Item = FilePreviewersOrderBody.shape.items.element;
+const row = (p) => ({
+    id: `${p.plugin}/${p.id}`,
+    name: p.title.en,
+    state: p.disabled ? "disabled" : "enabled",
+    plugin: p.plugin,
+    kind: p.kind,
+    position: p.position,
+});
+/**
+ * File previewer operations (the `extensions` domain): the org's order of the previewers its
+ * extensions provide and which are off (org admins, `org.extensions.manage`). Rendering a preview
+ * is the web's (`transport`).
+ */
+let PreviewersOperations = class PreviewersOperations {
+    registry;
+    previewers;
+    constructor(registry, previewers) {
+        this.registry = registry;
+        this.previewers = previewers;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "extensions.previewers",
+                description: "List the file previewers of the org's enabled extensions in the org's order (org admins): which extension provides each, its kind and whether the org switched it off. The first previewer that takes a file opens it.",
+                input: z.object({}).strict(),
+                example: {},
+                authz: { orgAction: "org.extensions.manage" },
+                mirrors: ["GET /api/v1/orgs/:orgId/file-previewers"],
+                confirm: "read",
+                run: async (_input, ctx) => {
+                    const items = await this.previewers.list(ctx.orgId);
+                    return { items: items.map(row), total: items.length };
+                },
+            }),
+            defineOperation({
+                id: "extensions.set-previewers",
+                description: "Set the org's order of file previewers and which are off (org admins): items lists { plugin, id, disabled } first to last, and previewers not listed follow in their usual order. Read the current list with extensions.previewers first; an item that is not a previewer of an enabled extension, or is listed twice, is refused.",
+                input: z
+                    .object({
+                    items: z.array(Item.strict()).max(500),
+                })
+                    .strict(),
+                example: { items: [{ plugin: "viewer-markdown", id: "markdown", disabled: false }] },
+                authz: { orgAction: "org.extensions.manage" },
+                mirrors: ["PUT /api/v1/orgs/:orgId/file-previewers"],
+                confirm: "org",
+                errors: [
+                    {
+                        code: "validation_failed",
+                        next: "An item is not a previewer of an extension enabled in this org, or is listed twice; take plugin and id from extensions.previewers.",
+                    },
+                ],
+                precheck: async (i, ctx) => {
+                    const known = new Set((await this.previewers.list(ctx.orgId)).map((p) => `${p.plugin}/${p.id}`));
+                    const seen = new Set();
+                    for (const x of i.items) {
+                        const k = `${x.plugin}/${x.id}`;
+                        if (!known.has(k) || seen.has(k)) {
+                            return {
+                                ok: false,
+                                code: "validation_failed",
+                                message: `${k} is not a previewer of an extension enabled in this organization, or is listed twice`,
+                            };
+                        }
+                        seen.add(k);
+                    }
+                    return { ok: true };
+                },
+                summary: (i) => {
+                    const off = i.items.filter((x) => x.disabled).map((x) => `${x.plugin}/${x.id}`);
+                    const first = i.items.slice(0, 3).map((x) => named(`${x.plugin}/${x.id}`));
+                    return {
+                        zh: `设置文件预览器的顺序：${i.items.length} 项在前（${first.join("、") || "无"}${i.items.length > 3 ? "…" : ""}），其中 ${off.length} 项关闭`,
+                        en: `Set the order of file previewers: ${i.items.length} first (${first.join(", ") || "none"}${i.items.length > 3 ? ", …" : ""}), ${off.length} of them switched off`,
+                    };
+                },
+                run: async (input, ctx) => {
+                    const items = await this.previewers.put(ctx.orgId, input.items, { accountId: ctx.actorAccountId }, viaAgent("extensions.set-previewers", ctx));
+                    return { items: items.map(row), total: items.length };
+                },
+            }),
+        ]);
+    }
+};
+PreviewersOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(PreviewerRegistry))
+], PreviewersOperations);
+export { PreviewersOperations };

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

@@ -9,12 +9,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 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 { asToolError, viaAgent } from "./errors.js";
+import { viaAgent } from "./errors.js";
 import { Cursor, pageOf, startOf } from "./paging.js";
-const Note = z.string().max(1000);
 /** A request as the requester reads it (no org name: it is this org's). */
 const view = (r) => ({
     id: r.id,
@@ -28,6 +28,25 @@ const view = (r) => ({
     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
@@ -59,11 +78,8 @@ let RequestsOperations = class RequestsOperations {
                 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: z.string().min(1).max(100),
-                    kind: z.enum(["enable", "access"]),
-                    note: Note.optional(),
-                })
+                    .object({ itemId: CatalogItemPathParams.shape.itemId.max(100) })
+                    .extend(CatalogRequestBody.shape)
                     .strict(),
                 example: {
                     itemId: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c",
@@ -96,21 +112,14 @@ let RequestsOperations = class RequestsOperations {
                         zh: `向超级管理员申请插件 ${i.itemId} 的使用权`,
                         en: `Request access to plugin ${i.itemId} from the super admin`,
                     },
-                run: async (input, ctx) => asToolError(async () => ({
+                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: z
-                    .object({
-                    marketplaceId: z.string().min(1).max(100),
-                    name: z.string().min(1).max(214),
-                    version: z.string().min(1).max(100),
-                    note: Note.optional(),
-                })
-                    .strict(),
+                input: CatalogMarketplaceRequestBody,
                 example: { marketplaceId: "official", name: "github", version: "1.4.0" },
                 authz: { orgAction: "catalog.decide" },
                 mirrors: ["POST /api/v1/orgs/:orgId/marketplace-requests"],
@@ -133,14 +142,43 @@ let RequestsOperations = class RequestsOperations {
                     zh: `申请从市场导入插件 ${i.name} ${i.version}`,
                     en: `Request the import of plugin ${i.name} ${i.version} from a marketplace`,
                 }),
-                run: async (input, ctx) => asToolError(async () => ({
+                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);
+                },
             }),
         ]);
     }

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

@@ -1,4 +1,5 @@
 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";
 /**
@@ -8,6 +9,9 @@ import { PlatformOperations } from "../registry.js";
 export declare class SkillsOperations implements OnModuleInit {
     private readonly registry;
     private readonly skills;
-    constructor(registry: PlatformOperations, skills: SkillsService);
+    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

@@ -9,12 +9,17 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
+import { OwnedItems } from "../../catalog/owned-items.js";
+import { SkillCreateFields, 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 { asToolError, viaAgent } from "./errors.js";
+import { precheckBy, viaAgent } from "./errors.js";
+import { named, orElse } from "./summary.js";
 const NoInput = z.object({}).strict();
-const SkillId = z.object({ skillId: z.string().min(1).max(100) }).strict();
+const SkillId = z.object({ skillId: SkillPathParams.shape.id.max(100) }).strict();
+const Create = SkillCreateFields.shape;
+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.
@@ -22,9 +27,15 @@ const SkillId = z.object({ skillId: z.string().min(1).max(100) }).strict();
 let SkillsOperations = class SkillsOperations {
     registry;
     skills;
-    constructor(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([
@@ -45,18 +56,20 @@ let SkillsOperations = class SkillsOperations {
                 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) => asToolError(() => this.skills.get(ctx.orgId, input.skillId)),
+                run: async (input, ctx) => this.skills.get(ctx.orgId, input.skillId),
             }),
             defineOperation({
                 id: "skills.create",
                 description: "Create an org skill from text: a name, a one-line description of when to use it, and the SKILL.md body. A skill of that name must not exist yet. Uploads of packages are done on the web.",
+                // the route's text form, its bounds tightened for the model (a SKILL.md up to 100k chars)
                 input: z
                     .object({
-                    name: z.string().min(1).max(64),
-                    description: z.string().min(1).max(1024),
-                    body: z.string().min(1).max(100_000),
-                    shareable: z.boolean().optional(),
+                    name: Create.name.unwrap().max(64),
+                    description: Create.description.unwrap(),
+                    body: Create.body.unwrap().min(1).max(100_000),
+                    shareable: Create.shareable,
                 })
                     .strict(),
                 example: {
@@ -66,26 +79,130 @@ let SkillsOperations = class SkillsOperations {
                 },
                 authz: { orgAction: "skills.manage" },
                 mirrors: ["POST /api/v1/orgs/:orgId/skills"],
+                // packages are uploaded on the web
+                omits: ["uploadId"],
                 confirm: "org",
                 errors: [
                     {
                         code: "skill.name_exists",
                         next: "A skill of that name exists: pick another name, or read the existing one with skills.get.",
                     },
+                    {
+                        code: "validation_failed",
+                        next: "Fix the SKILL.md as the message says (name, description, body), then call again.",
+                    },
+                    {
+                        code: "catalog.custom_disabled",
+                        next: {
+                            superAdmin: "The platform does not allow custom skills: allow them in the admin console under Settings, then call again.",
+                            orgAdmin: "The platform does not allow custom skills; ask the super admin, or use a platform skill from skills.list.",
+                            member: "The platform does not allow custom skills; use a platform skill from skills.list, or ask an org admin.",
+                        },
+                    },
                 ],
+                precheck: (i, ctx) => precheckBy(() => this.skills.checkCreateFromText(ctx.orgId, i)),
                 summary: (i) => i.shareable === true
                     ? {
                         zh: `新建组织技能「${i.name}」（可共享给其他组织）`,
                         en: `Create org skill "${i.name}" (shared with other orgs)`,
                     }
                     : { zh: `新建组织技能「${i.name}」`, en: `Create org skill "${i.name}"` },
-                run: async (input, ctx) => asToolError(() => this.skills.createFromText(ctx.orgId, ctx.actorAccountId, {
+                run: async (input, ctx) => this.skills.createFromText(ctx.orgId, ctx.actorAccountId, {
                     name: input.name,
                     description: input.description,
                     body: input.body,
                     ...(input.shareable !== undefined && { shareable: input.shareable }),
                     auditDetail: viaAgent("skills.create", ctx),
-                })),
+                }),
+            }),
+            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),
+                    }),
+                }),
             }),
         ]);
     }
@@ -93,6 +210,7 @@ let SkillsOperations = class SkillsOperations {
 SkillsOperations = __decorate([
     Injectable(),
     __param(0, Inject(PlatformOperations)),
-    __param(1, Inject(SkillsService))
+    __param(1, Inject(SkillsService)),
+    __param(2, Inject(OwnedItems))
 ], SkillsOperations);
 export { SkillsOperations };

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

@@ -0,0 +1,23 @@
+import type { PluginUnavailableReason } from "../../catalog/catalog-content.js";
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import { type ErrorRole } from "../errors.js";
+import type { OperationContext, OperationErrorNext } from "../operation.js";
+/** The next step for an unavailable plugin or extension, keyed by role. */
+export declare function unavailableNext(reason: PluginUnavailableReason, name: string): OperationErrorNext;
+/** Why it cannot be used: "The extension of plugin "X" is not running on the platform: … (reason)." */
+export declare function unavailableMessage(reason: PluginUnavailableReason, name: string): string;
+/** The fields an unavailable list row or detail adds: the reason and the role's next step. */
+export declare function unavailableFields(reason: PluginUnavailableReason | undefined, name: string, role: ErrorRole): {
+    reason?: PluginUnavailableReason;
+    next?: string;
+};
+/**
+ * The actor's role for next steps: the one the tool derived from this call's actor facts
+ * (`ctx.errorRole`), else read now with {@link errorRoleFor} (a context no tool call is behind).
+ */
+export declare function roleFor(db: KernelSchemaDb, ctx: OperationContext): Promise<ErrorRole>;
+/**
+ * The actor's role for next steps, read now (the super admin first, then an org admin): the
+ * fallback of {@link roleFor}, the same rule as `errorRoleOf` over `PlatformActor` facts.
+ */
+export declare function errorRoleFor(db: KernelSchemaDb, orgId: string, accountId: string): Promise<ErrorRole>;

package/dist/platform/ops/unavailable.js

@@ -0,0 +1,111 @@
+import { errorRoleOf, resolveNext } from "../errors.js";
+/**
+ * What an unavailable plugin or extension tells the model (Platform tool spec §14.2 problems 1
+ * and 3): what is missing, and the next step for the actor's role. Only the super admin gets the
+ * admin console path; nothing names a config field or carries a value.
+ */
+/** What is missing, per reason (model-visible English, completes "…is not running on the platform: "). */
+const MISSING = {
+    plugin_disabled: "the super admin stopped the plugin on the platform",
+    not_deployed: "its extension is not installed on the platform",
+    needs_deployment_config: "it is installed, but its deployment config is missing or invalid",
+    pending_approval: "it is installed, but its permissions wait for the super admin's approval",
+    pending_migration: "the platform is still preparing it (database migration)",
+    loading: "the platform is still loading it",
+    dependency: "it requires an extension point that no running extension provides",
+    failed: "it failed to load on the platform",
+    deployment_disabled: "the super admin disabled it on the platform",
+};
+/** No request operation reaches the super admin for these (requests.create: enable / access only). */
+const TELL_SUPER_ADMIN = "There is no request operation for this (requests.create covers enabling and access only), so tell the super admin directly.";
+/** The member's step: inside the org, never the admin console. */
+const memberNext = (name) => `Ask an org admin: the super admin must set up ${name} on the platform before anyone in the org can use it.`;
+/** The next step for an unavailable plugin or extension, keyed by role. */
+export function unavailableNext(reason, name) {
+    const adminPath = `Open the admin console → Extensions → ${name}`;
+    switch (reason) {
+        case "loading":
+        case "pending_migration":
+            return `The platform is still bringing ${name} up; wait a minute and check again with plugins.get or extensions.list.`;
+        case "plugin_disabled":
+            return {
+                superAdmin: "The plugin is stopped on the platform: turn it back on in the admin console under Plugins, then call again.",
+                orgAdmin: "The super admin stopped this plugin on the platform; ask them.",
+                member: "The super admin stopped this plugin on the platform; nothing can switch it on here.",
+            };
+        case "needs_deployment_config":
+            return {
+                superAdmin: `${adminPath} → fill in the deployment config; once it loads, switch the plugin on again.`,
+                orgAdmin: `Only the super admin can fill in the deployment config of ${name}. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "pending_approval":
+            return {
+                superAdmin: `${adminPath} → review and approve its permissions; once it loads, switch the plugin on again.`,
+                orgAdmin: `Only the super admin can approve the permissions of ${name}. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "dependency":
+            return {
+                superAdmin: `${adminPath} to see the extension point it requires, then install or enable an extension that provides it.`,
+                orgAdmin: `Only the super admin can provide what ${name} requires. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "failed":
+            return {
+                superAdmin: `${adminPath} to see why it failed to load; fix its deployment config or reinstall it.`,
+                orgAdmin: `Only the super admin can fix ${name}, which failed to load. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "deployment_disabled":
+            return {
+                superAdmin: `${adminPath} → enable it; once it loads, switch the plugin on again.`,
+                orgAdmin: `Only the super admin can enable ${name} on the platform. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "not_deployed":
+            return {
+                superAdmin: `Install the extension of ${name}: admin console → Extensions (or update the plugin in the admin console under Plugins), then switch it on again.`,
+                orgAdmin: `Only the super admin can install the extension of ${name}. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+    }
+}
+/** Why it cannot be used: "The extension of plugin "X" is not running on the platform: … (reason)." */
+export function unavailableMessage(reason, name) {
+    if (reason === "plugin_disabled")
+        return `Plugin "${name}" is unavailable: ${MISSING[reason]}.`;
+    return `The extension of "${name}" is not running on the platform: ${MISSING[reason]} (${reason}).`;
+}
+/** The fields an unavailable list row or detail adds: the reason and the role's next step. */
+export function unavailableFields(reason, name, role) {
+    if (reason === undefined)
+        return {};
+    const next = resolveNext(unavailableNext(reason, name), role);
+    return { reason, ...(next !== undefined && { next }) };
+}
+/**
+ * The actor's role for next steps: the one the tool derived from this call's actor facts
+ * (`ctx.errorRole`), else read now with {@link errorRoleFor} (a context no tool call is behind).
+ */
+export function roleFor(db, ctx) {
+    return ctx.errorRole !== undefined
+        ? Promise.resolve(ctx.errorRole)
+        : errorRoleFor(db, ctx.orgId, ctx.actorAccountId);
+}
+/**
+ * The actor's role for next steps, read now (the super admin first, then an org admin): the
+ * fallback of {@link roleFor}, the same rule as `errorRoleOf` over `PlatformActor` facts.
+ */
+export async function errorRoleFor(db, orgId, accountId) {
+    const row = await db
+        .selectFrom("accounts")
+        .leftJoin("memberships", (j) => j.onRef("memberships.account_id", "=", "accounts.id").on("memberships.org_id", "=", orgId))
+        .select(["accounts.is_super_admin", "accounts.status", "memberships.role"])
+        .where("accounts.id", "=", accountId)
+        .executeTakeFirst();
+    return errorRoleOf({
+        role: row?.role ?? null,
+        isSuperAdmin: row?.is_super_admin === true && row.status === "active",
+    });
+}

package/dist/platform/parity.d.ts

@@ -0,0 +1,33 @@
+import type { PlatformOperation } from "./operation.js";
+import type { RouteSchemas } from "./route-schemas.js";
+/** One difference between an operation's input and its mirrored route (spec §14.5 item 3). */
+export interface ParityFinding {
+    op: string;
+    route: string;
+    /** The operation field (or declaration entry) it is about; absent when about the whole route. */
+    field?: string;
+    message: string;
+}
+/** What {@link inputParity} reads of an operation. */
+export type ParityOperation = Pick<PlatformOperation, "id" | "input" | "mirrors"> & Partial<Pick<PlatformOperation, "omits" | "extras" | "renames" | "loosens">>;
+/**
+ * Compares an operation's input with one mirrored route's body + query + path params (spec
+ * §14.5 item 3), on their input JSON Schemas:
+ * - each input field is compared with the route field of the same name, or the route path its
+ *   `renames` entry names (`skillId` → `id`, `name` → `definition.name`): the same type (an
+ *   operation `integer` fits a route `number`), enum values a subset, bounds no looser
+ *   (`maxLength` / `maximum` / `maxItems` at most the route's, the lower bounds at least), the
+ *   same `pattern` and `format`, and required where the route requires it; nested objects,
+ *   arrays and records recursively (a nested optional route field the operation leaves out is
+ *   allowed, a required one is not);
+ * - a `loosens` entry names an input field allowed to accept more than the route (with the
+ *   reason); it is still compared by type, and an entry that loosens nothing is stale;
+ * - a top-level route field the input neither has nor renames into is listed in `omits`, an input
+ *   field with no route counterpart in `extras`; stale entries of either are findings.
+ */
+export declare function inputParity(op: ParityOperation, route: RouteSchemas): ParityFinding[];
+/**
+ * {@link inputParity} of every operation against each route it mirrors; a mirrored route whose
+ * schemas are not registered is a finding too (a removed route is `check:platform-ops`'s orphan).
+ */
+export declare function checkInputParity(ops: readonly ParityOperation[], routes: readonly RouteSchemas[]): ParityFinding[];