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

package/dist/catalog/org-catalog.service.js

@@ -10,6 +10,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
+import { ExtensionAvailability } from "../extensions/unavailable.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
@@ -47,9 +48,12 @@ let OrgCatalogService = class OrgCatalogService {
     pluginInstaller;
     log;
     txHost;
+    availability;
     constructor(kdb, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock, storage, registry, pluginInstaller, log, txHost) {
+    orgLock, storage, registry, pluginInstaller, log, txHost, 
+    /** Why a plugin's extension cannot run (the `unavailable` state's reason). */
+    availability) {
         this.kdb = kdb;
         this.orgLock = orgLock;
         this.storage = storage;
@@ -57,6 +61,7 @@ let OrgCatalogService = class OrgCatalogService {
         this.pluginInstaller = pluginInstaller;
         this.log = log;
         this.txHost = txHost;
+        this.availability = availability;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
     get db() {
@@ -158,6 +163,16 @@ let OrgCatalogService = class OrgCatalogService {
         const configured = new Set(configs.map((c) => c.plugin));
         const owners = await ownersOf(this.db, items.flatMap((i) => (i.owner_org_id === null ? [] : [i.owner_org_id])));
         const loaded = new Map(this.registry.manifests().map((x) => [x.name, x]));
+        // the extensions of the latest versions that are not loaded: why (the `unavailable` reason)
+        const extensionOf = (i) => {
+            const v = versions.find((x) => x.item_id === i.id && x.version === i.latest_version);
+            const m = v?.manifest;
+            return m?.extension ? m.name : undefined;
+        };
+        const unloaded = await this.availability.unavailable(items.flatMap((i) => {
+            const n = extensionOf(i);
+            return n === undefined ? [] : [n];
+        }));
         const out = [];
         for (const i of items) {
             // Another org sees only an org-owned plugin's applied version, never one its owner
@@ -172,12 +187,23 @@ let OrgCatalogService = class OrgCatalogService {
             const scope = i.builtin ? "all" : i.scope;
             const wanted = wantedOn(i, inList.has(i.id), sw.get(i.id) ?? null);
             let state;
+            let reason;
+            const extName = extensionOf(i);
+            const why = extName === undefined ? undefined : unloaded.get(extName);
             if (i.awaiting_confirmation)
                 state = "awaiting_confirmation";
-            else if (i.disabled)
+            else if (i.disabled) {
                 state = "unavailable";
+                reason = "plugin_disabled";
+            }
             else if (requestable(i, inList.has(i.id)))
                 state = "not_offered";
+            // not installed here and its extension cannot run: switching it on would fail (spec §14.2
+            // problem 1); an installed one keeps its state (an org admin can still switch it off)
+            else if (!a && why !== undefined) {
+                state = "unavailable";
+                reason = why.reason;
+            }
             else if (a) {
                 // An on connector template without a connector here (ruling P2-10)
                 const missing = await this.pluginInstaller.missingConnectors(orgId, i.id);
@@ -208,6 +234,7 @@ let OrgCatalogService = class OrgCatalogService {
                 scope,
                 builtin: i.builtin,
                 state,
+                ...(reason !== undefined && { reason }),
                 switchable: state !== "not_offered" && state !== "awaiting_confirmation" && switchable(i),
                 notDeployed: latest !== undefined && undeployed.has(i.id),
                 installed: a
@@ -467,7 +494,9 @@ let OrgCatalogService = class OrgCatalogService {
      * install writes the switch row false in the uninstall's transaction (an `all` item then stays
      * off in the org); removing a failed or stale one writes none.
      */
-    async uninstall(orgId, actor, installId, actorTokenId) {
+    async uninstall(orgId, actor, installId, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
         if (!UUID_RE.test(installId))
             throw new ApiError("plugin.install_not_found", "Plugin install not found");
         const row = await this.db
@@ -482,7 +511,10 @@ let OrgCatalogService = class OrgCatalogService {
         if (row !== undefined && live && !switchable(row)) {
             throw new ApiError("plugin.scope_locked", "This plugin is built in: it is on for every organization and cannot be uninstalled here");
         }
-        return this.pluginInstaller.uninstall(orgId, actor, installId, actorTokenId !== undefined ? { actorTokenId } : {}, 
+        return this.pluginInstaller.uninstall(orgId, actor, installId, {
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            ...(auditDetail !== undefined && { auditDetail }),
+        }, 
         // only a live install was on: removing a failed or stale one writes no switch row, so an
         // item its scope wants stays wanted and the sync installs it again
         row !== undefined && live ? {} : undefined);
@@ -546,6 +578,7 @@ OrgCatalogService = __decorate([
     __param(3, Inject(ExtensionRegistry)),
     __param(4, Inject(PluginInstaller)),
     __param(5, Inject(KERNEL_LOGGER)),
-    __param(6, Inject(TransactionHost))
+    __param(6, Inject(TransactionHost)),
+    __param(7, Inject(ExtensionAvailability))
 ], OrgCatalogService);
 export { OrgCatalogService };

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

@@ -6,6 +6,7 @@ import { OrgOverrides, type OrgOverrideView } from "../extensions/org-overrides.
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { type OrgToolSwitch, OrgToolSwitches, type OrgToolSwitchResult } from "../tools/org-tool-switches.js";
+import { OrgExtensionParams as ExtensionParams, OrgExtensionToolParams as ToolParams, OrgToolSwitchPut as ToolSwitchPut } from "./org-extension.schemas.js";
 import { OrgExtensionSwitch } from "./org-extension-switch.js";
 import type { UninstallPreview } from "./plugin-install.js";
 declare const PutBody: z.ZodObject<{
@@ -26,18 +27,6 @@ declare const OverridesPut: z.ZodObject<{
 declare const OverridesTake: z.ZodObject<{
     paths: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
-declare const ToolSwitchPut: z.ZodObject<{
-    enabled: z.ZodBoolean;
-    confirm: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-/** Route parameters of the overrides and tool switch routes (decision R20). */
-declare const ExtensionParams: z.ZodObject<{
-    extension: z.ZodString;
-}, z.core.$strip>;
-declare const ToolParams: z.ZodObject<{
-    extension: z.ZodString;
-    tool: z.ZodString;
-}, z.core.$strip>;
 /**
  * One extension of the org list: the org view plus the plugin's display name and the extension
  * points it provides (`channel@1`, `web-search@1`, … the names only, also for members).

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

@@ -18,6 +18,7 @@ import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { roleAtLeast } from "../orgs/roles.js";
 import { OrgToolSwitches, } from "../tools/org-tool-switches.js";
+import { OrgExtensionParams as ExtensionParams, OrgExtensionToolParams as ToolParams, OrgToolSwitchPut as ToolSwitchPut, } from "./org-extension.schemas.js";
 import { OrgExtensionSwitch } from "./org-extension-switch.js";
 const PutBody = z
     .object({
@@ -57,18 +58,8 @@ const OverridesPut = z
 const OverridesTake = z
     .object({ paths: z.array(z.string().min(1).max(256)).min(1).max(200) })
     .strict();
-const ToolSwitchPut = z
-    .object({
-    enabled: z.boolean(),
-    /** The hash of the switch-off preview, to confirm turning the tool off. */
-    confirm: z.string().min(1).max(128).optional(),
-})
-    .strict();
 class OrgToolSwitchPutBody extends createZodDto(ToolSwitchPut, "OrgToolSwitchPutBody") {
 }
-/** Route parameters of the overrides and tool switch routes (decision R20). */
-const ExtensionParams = z.object({ extension: z.string().min(1).max(64) });
-const ToolParams = ExtensionParams.extend({ tool: z.string().min(1).max(64) });
 class OrgExtensionParamsDto extends createZodDto(ExtensionParams, "OrgExtensionParams") {
 }
 class OrgExtensionToolParamsDto extends createZodDto(ToolParams, "OrgExtensionToolParams") {

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

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** Route parameters of the overrides and tool switch routes (decision R20). */
+export declare const OrgExtensionParams: z.ZodObject<{
+    extension: z.ZodString;
+}, z.core.$strip>;
+export declare const OrgExtensionToolParams: z.ZodObject<{
+    extension: z.ZodString;
+    tool: z.ZodString;
+}, z.core.$strip>;
+export declare const OrgToolSwitchPut: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    confirm: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const ORG_EXTENSION_ROUTES: readonly RouteSchemas[];

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

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/** Route parameters of the overrides and tool switch routes (decision R20). */
+export const OrgExtensionParams = z.object({ extension: z.string().min(1).max(64) });
+export const OrgExtensionToolParams = OrgExtensionParams.extend({
+    tool: z.string().min(1).max(64),
+});
+export const OrgToolSwitchPut = z
+    .object({
+    enabled: z.boolean(),
+    /** The hash of the switch-off preview, to confirm turning the tool off. */
+    confirm: z.string().min(1).max(128).optional(),
+})
+    .strict();
+export const ORG_EXTENSION_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/extensions" },
+    { route: "GET /api/v1/orgs/:orgId/extensions/:extension/tools", params: OrgExtensionParams },
+    {
+        route: "PUT /api/v1/orgs/:orgId/extensions/:extension/tools/:tool",
+        params: OrgExtensionToolParams,
+        body: OrgToolSwitchPut,
+    },
+];

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

@@ -1,27 +1,11 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import type { CatalogItemView } from "./catalog.service.js";
 import { CatalogScopeService } from "./catalog-scope.service.js";
 import { OrgPluginUploads, type OrgUploadOutcome, type OrgUploadReview } from "./org-plugin-uploads.js";
+import { OrgUploadConfirmBody as ConfirmBody, OrgOwnedDeleteBody as DeleteBody, OrgOwnedPluginParams as OwnedParams, OrgOwnedShareableBody as ShareableBody, OrgUploadStagingParams as StagingParams } from "./org-plugin-uploads.schemas.js";
 import { type OwnedDeletePreview, OwnedItems } from "./owned-items.js";
-declare const StagingParams: z.ZodObject<{
-    stagingId: z.ZodString;
-}, z.core.$strip>;
-declare const OwnedParams: z.ZodObject<{
-    id: z.ZodString;
-}, z.core.$strip>;
-declare const ConfirmBody: z.ZodObject<{
-    reviewHash: z.ZodString;
-    shareable: z.ZodOptional<z.ZodBoolean>;
-    pinnedSuggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>;
-declare const ShareableBody: z.ZodObject<{
-    shareable: z.ZodBoolean;
-}, z.core.$strict>;
-declare const DeleteBody: z.ZodObject<{
-    previewHash: z.ZodString;
-}, z.core.$strict>;
 /**
  * An org admin's plugin uploads (`/api/v1/orgs/:orgId/catalog/uploads/*`, spec §14, rulings P3-7,
  * P3-8): a `.tgz` without an extension, prepared (one review) and confirmed like the super admin's
@@ -95,4 +79,3 @@ export declare class OrgOwnedPluginsController {
      */
     withdraw(principal: Principal, org: OrgContext, params: z.infer<typeof OwnedParams>): Promise<void>;
 }
-export {};

package/dist/catalog/org-plugin-uploads.controller.js

@@ -8,7 +8,6 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Delete, Get, HttpCode, Inject, Post, Put, Req } from "@nestjs/common";
-import { z } from "zod";
 import { ApiError } from "../errors.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
@@ -16,29 +15,17 @@ import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { CatalogScopeService } from "./catalog-scope.service.js";
 import { OrgPluginUploads, } from "./org-plugin-uploads.js";
+import { OrgUploadConfirmBody as ConfirmBody, OrgOwnedDeleteBody as DeleteBody, OrgOwnedPluginParams as OwnedParams, OrgOwnedShareableBody as ShareableBody, OrgUploadStagingParams as StagingParams, } from "./org-plugin-uploads.schemas.js";
 import { OwnedItems } from "./owned-items.js";
-const StagingParams = z.object({ stagingId: z.string().min(1).max(100) });
-const OwnedParams = z.object({ id: z.string().min(1).max(100) });
-const ConfirmBody = z
-    .object({
-    reviewHash: z.string().min(1).max(128),
-    /** The org shares the new item with other orgs (default false, P3-16). */
-    shareable: z.boolean().optional(),
-    /** Skill names suggested as pinned (spec §9.1); omitted keeps the plugin's flags. */
-    pinnedSuggestions: z.array(z.string().min(1).max(64)).max(50).optional(),
-})
-    .strict();
-class OrgUploadStagingParams extends createZodDto(StagingParams, "OrgUploadStagingParams") {
+class OrgUploadStagingParamsDto extends createZodDto(StagingParams, "OrgUploadStagingParams") {
 }
-class OrgUploadConfirmBody extends createZodDto(ConfirmBody, "OrgUploadConfirmBody") {
+class OrgUploadConfirmBodyDto extends createZodDto(ConfirmBody, "OrgUploadConfirmBody") {
 }
-class OrgOwnedPluginParams extends createZodDto(OwnedParams, "OrgOwnedPluginParams") {
+class OrgOwnedPluginParamsDto extends createZodDto(OwnedParams, "OrgOwnedPluginParams") {
 }
-const ShareableBody = z.object({ shareable: z.boolean() }).strict();
-const DeleteBody = z.object({ previewHash: z.string().min(1).max(128) }).strict();
-class OrgOwnedShareableBody extends createZodDto(ShareableBody, "OrgOwnedShareableBody") {
+class OrgOwnedShareableBodyDto extends createZodDto(ShareableBody, "OrgOwnedShareableBody") {
 }
-class OrgOwnedDeleteBody extends createZodDto(DeleteBody, "OrgOwnedDeleteBody") {
+class OrgOwnedDeleteBodyDto extends createZodDto(DeleteBody, "OrgOwnedDeleteBody") {
 }
 const actorOpts = (actor) => {
     const tokenId = patTokenId(actor);
@@ -107,7 +94,7 @@ __decorate([
     Get(":stagingId"),
     OrgAction("catalog.upload"),
     __param(0, CurrentOrg()),
-    __param(1, ZParam(OrgUploadStagingParams))
+    __param(1, ZParam(OrgUploadStagingParamsDto))
 ], OrgPluginUploadsController.prototype, "staged", null);
 __decorate([
     Post(":stagingId/confirm"),
@@ -115,8 +102,8 @@ __decorate([
     OrgAction("catalog.upload"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZParam(OrgUploadStagingParams)),
-    __param(3, ZBody(OrgUploadConfirmBody))
+    __param(2, ZParam(OrgUploadStagingParamsDto)),
+    __param(3, ZBody(OrgUploadConfirmBodyDto))
 ], OrgPluginUploadsController.prototype, "confirm", null);
 OrgPluginUploadsController = __decorate([
     Controller("api/v1/orgs/:orgId/catalog/uploads"),
@@ -178,15 +165,15 @@ __decorate([
     OrgAction("catalog.upload"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZParam(OrgOwnedPluginParams)),
-    __param(3, ZBody(OrgOwnedShareableBody))
+    __param(2, ZParam(OrgOwnedPluginParamsDto)),
+    __param(3, ZBody(OrgOwnedShareableBodyDto))
 ], OrgOwnedPluginsController.prototype, "setShareable", null);
 __decorate([
     Post(":id/delete/preview"),
     HttpCode(200),
     OrgAction("catalog.upload"),
     __param(0, CurrentOrg()),
-    __param(1, ZParam(OrgOwnedPluginParams))
+    __param(1, ZParam(OrgOwnedPluginParamsDto))
 ], OrgOwnedPluginsController.prototype, "previewDelete", null);
 __decorate([
     Post(":id/delete"),
@@ -194,8 +181,8 @@ __decorate([
     OrgAction("catalog.upload"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZParam(OrgOwnedPluginParams)),
-    __param(3, ZBody(OrgOwnedDeleteBody))
+    __param(2, ZParam(OrgOwnedPluginParamsDto)),
+    __param(3, ZBody(OrgOwnedDeleteBodyDto))
 ], OrgOwnedPluginsController.prototype, "delete", null);
 __decorate([
     Delete(":id/pending"),
@@ -203,7 +190,7 @@ __decorate([
     OrgAction("catalog.upload"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZParam(OrgOwnedPluginParams))
+    __param(2, ZParam(OrgOwnedPluginParamsDto))
 ], OrgOwnedPluginsController.prototype, "withdraw", null);
 OrgOwnedPluginsController = __decorate([
     Controller("api/v1/orgs/:orgId/owned-plugins"),

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

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const OrgUploadStagingParams: z.ZodObject<{
+    stagingId: z.ZodString;
+}, z.core.$strip>;
+export declare const OrgOwnedPluginParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const OrgUploadConfirmBody: z.ZodObject<{
+    reviewHash: z.ZodString;
+    shareable: z.ZodOptional<z.ZodBoolean>;
+    pinnedSuggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const OrgOwnedShareableBody: z.ZodObject<{
+    shareable: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const OrgOwnedDeleteBody: z.ZodObject<{
+    previewHash: z.ZodString;
+}, z.core.$strict>;
+export declare const ORG_PLUGIN_UPLOAD_ROUTES: readonly RouteSchemas[];

package/dist/catalog/org-plugin-uploads.schemas.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+export const OrgUploadStagingParams = z.object({ stagingId: z.string().min(1).max(100) });
+export const OrgOwnedPluginParams = z.object({ id: z.string().min(1).max(100) });
+export const OrgUploadConfirmBody = z
+    .object({
+    reviewHash: z.string().min(1).max(128),
+    /** The org shares the new item with other orgs (default false, P3-16). */
+    shareable: z.boolean().optional(),
+    /** Skill names suggested as pinned (spec §9.1); omitted keeps the plugin's flags. */
+    pinnedSuggestions: z.array(z.string().min(1).max(64)).max(50).optional(),
+})
+    .strict();
+export const OrgOwnedShareableBody = z.object({ shareable: z.boolean() }).strict();
+export const OrgOwnedDeleteBody = z.object({ previewHash: z.string().min(1).max(128) }).strict();
+export const ORG_PLUGIN_UPLOAD_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/catalog/uploads/:stagingId", params: OrgUploadStagingParams },
+    {
+        route: "PUT /api/v1/orgs/:orgId/owned-plugins/:id/shareable",
+        params: OrgOwnedPluginParams,
+        body: OrgOwnedShareableBody,
+    },
+    {
+        route: "POST /api/v1/orgs/:orgId/owned-plugins/:id/delete/preview",
+        params: OrgOwnedPluginParams,
+    },
+    {
+        route: "POST /api/v1/orgs/:orgId/owned-plugins/:id/delete",
+        params: OrgOwnedPluginParams,
+        body: OrgOwnedDeleteBody,
+    },
+    { route: "DELETE /api/v1/orgs/:orgId/owned-plugins/:id/pending", params: OrgOwnedPluginParams },
+];

package/dist/catalog/owned-items.d.ts

@@ -65,7 +65,9 @@ export declare class OwnedItems {
      * 409 `catalog.not_owned`); one it promoted writes its platform row too (pre-flight F16). Audits
      * `catalog.shareable_changed`.
      */
-    setShareable(orgId: string, actor: string, ref: OwnedRef, shareable: boolean, opts?: ActorOpts): Promise<void>;
+    setShareable(orgId: string, actor: string, ref: OwnedRef, shareable: boolean, opts?: ActorOpts & {
+        auditDetail?: Record<string, unknown>;
+    }): Promise<void>;
     /** {@link setShareable} of an org skill or agent template (named by the org row's id). */
     private setComponentShareable;
     /** The other live orgs the item is on in (P3-18, {@link orgsUsing}), by name. */
@@ -86,7 +88,9 @@ export declare class OwnedItems {
      * `owner_deleted` (another org using it keeps it, now the platform's), then the org row is
      * soft-deleted as before (audit `skill.deleted`). Not an org-scope skill of the org -> 404.
      */
-    deleteSkill(orgId: string, actor: string, skillId: string, opts?: ActorOpts): Promise<"transferred" | "removed">;
+    deleteSkill(orgId: string, actor: string, skillId: string, opts?: ActorOpts & {
+        auditDetail?: Record<string, unknown>;
+    }): Promise<"transferred" | "removed">;
     /**
      * What deleting the org's own agent template `id` does (ruling P4-12, as
      * {@link previewSkillDelete}): one it promoted that another org uses is `transferred` (`orgs`:

package/dist/catalog/owned-items.js

@@ -121,7 +121,7 @@ let OwnedItems = class OwnedItems {
             orgId,
             action: "catalog.shareable_changed",
             target: item.id,
-            detail: { name: item.name, shareable },
+            detail: { name: item.name, shareable, ...opts.auditDetail },
         });
     }
     /** {@link setShareable} of an org skill or agent template (named by the org row's id). */
@@ -165,6 +165,7 @@ let OwnedItems = class OwnedItems {
                 name: row.name,
                 shareable,
                 ...(row.link !== null && { platformId: row.link }),
+                ...opts.auditDetail,
             },
         });
     }
@@ -221,7 +222,7 @@ let OwnedItems = class OwnedItems {
         const outcome = row.link === null
             ? "removed"
             : await this.transferOrRemove({ kind: "skill", id: row.link }, "owner_deleted", actor, opts);
-        await this.skills.deleteOrgSkillIn(orgId, row.id, actor, opts.actorTokenId);
+        await this.skills.deleteOrgSkillIn(orgId, row.id, actor, opts.actorTokenId, opts.auditDetail);
         return outcome;
     }
     /**
@@ -266,7 +267,12 @@ let OwnedItems = class OwnedItems {
             orgId,
             action: "agent_template.deleted",
             target: row.id,
-            detail: { name: row.name, outcome, ...(row.link !== null && { platformId: row.link }) },
+            detail: {
+                name: row.name,
+                outcome,
+                ...(row.link !== null && { platformId: row.link }),
+                ...opts.auditDetail,
+            },
         });
         return outcome;
     }
@@ -510,7 +516,13 @@ let OwnedItems = class OwnedItems {
             orgId: owner,
             action: "catalog.ownership_transferred",
             target: item.id,
-            detail: { name: item.name, fromOrgId: owner, reason, usedBy: others.map((o) => o.id) },
+            detail: {
+                name: item.name,
+                fromOrgId: owner,
+                reason,
+                usedBy: others.map((o) => o.id),
+                ...opts.auditDetail,
+            },
         });
         afterCommit(() => this.scope.enqueueSync(item.id));
         return "transferred";

package/dist/catalog/platform-components.d.ts

@@ -122,6 +122,8 @@ export interface OwnerVersion {
 export interface UploadActor {
     accountId: string;
     actorTokenId?: string;
+    /** Added to the audit detail (the Platform tool's `via`). */
+    auditDetail?: Record<string, unknown>;
 }
 /**
  * Writes the platform rows of a catalog version's components. Called by the import confirm that

package/dist/catalog/platform-components.js

@@ -346,6 +346,7 @@ let PlatformComponents = class PlatformComponents {
                 plugin: live.plugin_name,
                 from: live.current_version,
                 to,
+                ...actor.auditDetail,
             },
         });
     }
@@ -400,6 +401,7 @@ let PlatformComponents = class PlatformComponents {
                 plugin: live.plugin_name,
                 from: live.current_version,
                 to,
+                ...actor.auditDetail,
             },
         });
     }

package/dist/catalog/plugin-import.js

@@ -511,6 +511,7 @@ let PluginImport = class PluginImport {
                     extension: { sha256: extension.sha256, action: extension.action },
                 }),
                 ...(owner !== undefined && { orgId: owner.orgId }),
+                ...opts.auditDetail,
             },
         });
     }

package/dist/catalog/plugin-install.js

@@ -896,7 +896,7 @@ let PluginInstaller = class PluginInstaller {
             return null;
         const name = manifest.name;
         if (!this.registry.manifests().some((m) => m.name === name)) {
-            throw new ApiError("catalog.not_deployed", `The extension of plugin ${name} is not deployed; ask the super admin to install and enable it`);
+            throw new ApiError("catalog.not_deployed", `The extension of plugin ${name} is not running on the platform (not installed, waiting for its deployment config or permission approval, disabled, or failed to load); the org cannot switch it on until it runs`);
         }
         const enabled = await isExtensionEnabled(this.db, orgId, name);
         if (!enabled && (await disabledPluginItems(this.db, [name])).length > 0) {

package/dist/catalog/requests.service.d.ts

@@ -143,7 +143,8 @@ export declare class CatalogRequestsService {
      * A request for a catalog item (`POST /orgs/:orgId/catalog/:itemId/requests`): `enable`
      * (`catalog.request`, members and up) or `access` (`catalog.decide`, org admins), checked first.
      * The item as the org sees it: absent (missing, deleted, hidden, disabled for a member) ->
-     * `catalog.item_not_found`; disabled -> `catalog.item_disabled` for an org admin; `access` needs
+     * `catalog.item_not_found`; disabled -> `catalog.item_disabled` for an org admin; its extension
+     * unable to run on the platform -> `catalog.request_invalid`; `access` needs
      * `not_offered`, `enable` needs `off` (else `catalog.request_invalid`); a pending request of the
      * kind -> `catalog.request_pending`. Audits `catalog.requested`.
      */

package/dist/catalog/requests.service.js

@@ -95,7 +95,8 @@ let CatalogRequestsService = class CatalogRequestsService {
      * A request for a catalog item (`POST /orgs/:orgId/catalog/:itemId/requests`): `enable`
      * (`catalog.request`, members and up) or `access` (`catalog.decide`, org admins), checked first.
      * The item as the org sees it: absent (missing, deleted, hidden, disabled for a member) ->
-     * `catalog.item_not_found`; disabled -> `catalog.item_disabled` for an org admin; `access` needs
+     * `catalog.item_not_found`; disabled -> `catalog.item_disabled` for an org admin; its extension
+     * unable to run on the platform -> `catalog.request_invalid`; `access` needs
      * `not_offered`, `enable` needs `off` (else `catalog.request_invalid`); a pending request of the
      * kind -> `catalog.request_pending`. Audits `catalog.requested`.
      */
@@ -107,8 +108,11 @@ let CatalogRequestsService = class CatalogRequestsService {
         const [item] = await this.orgCatalog.list(orgId, actor, itemId);
         if (!item)
             throw itemNotFound();
-        if (item.state === "unavailable")
+        if (item.state === "unavailable" && item.reason === "plugin_disabled")
             throw itemDisabled();
+        if (item.state === "unavailable") {
+            throw new ApiError("catalog.request_invalid", `This plugin's extension cannot run on the platform now (${item.reason ?? "unavailable"}); only the super admin can fix that`);
+        }
         const want = input.kind === "access" ? "not_offered" : "off";
         if (item.state !== want) {
             throw new ApiError("catalog.request_invalid", input.kind === "access"

package/dist/channels/channels.schemas.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const ChannelCreateSchema: z.ZodObject<{
+    plugin: z.ZodString;
+    name: z.ZodString;
+    agentId: z.ZodString;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    unboundPolicy: z.ZodOptional<z.ZodEnum<{
+        anonymous: "anonymous";
+        bind: "bind";
+    }>>;
+}, z.core.$strict>;
+export declare const ChannelPatchSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    unboundPolicy: z.ZodOptional<z.ZodEnum<{
+        anonymous: "anonymous";
+        bind: "bind";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>>;
+    inboundMode: z.ZodOptional<z.ZodEnum<{
+        long_connection: "long_connection";
+        webhook: "webhook";
+    }>>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const ChannelPathParams: z.ZodObject<{
+    connectionId: z.ZodString;
+}, z.core.$strip>;
+export declare const CHANNEL_ROUTES: readonly RouteSchemas[];

package/dist/channels/channels.schemas.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+const Config = z.record(z.string().max(200), z.unknown());
+const Policy = z.enum(["bind", "anonymous"]);
+export const ChannelCreateSchema = z
+    .object({
+    plugin: z.string().min(1).max(214),
+    name: z.string().trim().min(1).max(100),
+    agentId: z.string().min(1).max(100),
+    config: Config,
+    unboundPolicy: Policy.optional(),
+})
+    .strict();
+export const ChannelPatchSchema = z
+    .object({
+    name: z.string().trim().min(1).max(100).optional(),
+    agentId: z.string().min(1).max(100).optional(),
+    unboundPolicy: Policy.optional(),
+    status: z.enum(["active", "disabled"]).optional(),
+    // webhook needs plugin support and channels.webhookBaseUrl (409 channel.webhook_unavailable)
+    inboundMode: z.enum(["long_connection", "webhook"]).optional(),
+    config: Config.optional(),
+})
+    .strict();
+export const ChannelPathParams = z.object({ connectionId: z.string().min(1).max(100) });
+export const CHANNEL_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/channels" },
+    { route: "GET /api/v1/orgs/:orgId/channels/:connectionId", params: ChannelPathParams },
+    {
+        route: "PATCH /api/v1/orgs/:orgId/channels/:connectionId",
+        params: ChannelPathParams,
+        body: ChannelPatchSchema,
+    },
+    { route: "DELETE /api/v1/orgs/:orgId/channels/:connectionId", params: ChannelPathParams },
+];