@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

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/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,216 @@
+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 { 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 { 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 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.
+ */
+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.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: Create.name.unwrap().max(64),
+                    description: Create.description.unwrap(),
+                    body: Create.body.unwrap().min(1).max(100_000),
+                    shareable: Create.shareable,
+                })
+                    .strict(),
+                example: {
+                    name: "weekly-report",
+                    description: "Use when asked to write the weekly status report.",
+                    body: "# Steps\n\n1. Collect this week's updates.\n2. Write the report.",
+                },
+                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) => 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),
+                    }),
+                }),
+            }),
+        ]);
+    }
+};
+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;
+    }
+}

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,118 @@
+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",
+    conflict: "it provides an extension point only one extension may provide, and another running extension already provides it",
+    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 "conflict":
+            return {
+                superAdmin: `${adminPath} to see which extension already provides the same extension point; disable that one (or uninstall it) and ${name} loads, no restart.`,
+                orgAdmin: `Only the super admin can resolve the conflict of ${name} with another extension. ${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[];