@capybara-hq/kernel 0.1.0-rc.14 → 0.1.0-rc.16

package/dist/catalog/plugin-import.js

@@ -8,11 +8,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { createHash, randomUUID } from "node:crypto";
-import { PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { appearanceIssues, PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
+import { ClientBuilds } from "../client/client-builds.service.js";
+import { checkClientFiles } from "../client/client-files.js";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionAdmin } from "../extensions/admin-view.js";
@@ -112,14 +114,17 @@ const reviewStale = (review) => new ApiError("plugin.review_stale", `The review
 const mismatch = (what) => new ApiError("marketplace.package_mismatch", `The downloaded package does not match the marketplace entry: ${what}`);
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
- * `catalog.legacy_format`; a failing theme (themes spec §5) -> `theme.invalid` (details
- * `[{ theme, errors }]`) or `theme.unreadable` (details `[{ theme, issues }]`, the failing pairs);
- * anything else -> `catalog.invalid_manifest` (issues as details).
+ * `catalog.legacy_format`; undeclared client code -> `client.undeclared`; a failing theme (themes
+ * spec §5) -> `theme.invalid` (details `[{ theme, errors }]`) or `theme.unreadable` (details
+ * `[{ theme, issues }]`, the failing pairs); anything else -> `catalog.invalid_manifest` (issues as
+ * details).
  */
 export function catalogPackageError(e) {
     const legacy = e.code === "catalog.legacy_format" || e.code === "extension.legacy_format";
     if (legacy)
         return new ApiError("catalog.legacy_format", e.message, e.issues);
+    if (e.code === "client.undeclared")
+        return new ApiError("client.undeclared", e.message);
     if (e.code === "theme.invalid" || e.code === "theme.unreadable") {
         return themeApiError(e);
     }
@@ -160,6 +165,7 @@ let PluginImport = class PluginImport {
     txHost;
     platform;
     maintenance;
+    clientBuilds;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     files;
     /**
@@ -180,7 +186,9 @@ let PluginImport = class PluginImport {
     /** The platform rows of a new item's components, written after the confirm's commit. */
     platform, 
     /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
-    maintenance) {
+    maintenance, 
+    /** The client build of a dropped org upload's package is deleted with it. */
+    clientBuilds) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.orgLock = orgLock;
@@ -197,6 +205,7 @@ let PluginImport = class PluginImport {
         this.txHost = txHost;
         this.platform = platform;
         this.maintenance = maintenance;
+        this.clientBuilds = clientBuilds;
         this.files = storage;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -341,6 +350,22 @@ let PluginImport = class PluginImport {
             ? await readingPackage(() => readExtensionPackage(bytes, { maxBytes, hostSdkVersion: SDK_VERSION }))
             : undefined;
         const content = this.checkContent(pkg, format);
+        // suggestedAppearance.theme against the themes the scan found (the manifest may not list them)
+        const appearance = appearanceIssues(m, pkg.themes.map((t) => t.id));
+        if (appearance.length > 0)
+            throw invalid(appearance);
+        // Client code (client extensions spec §9.1): the section re-checked and every file against it
+        // (keys, listed = present, sizes, sha384 recomputed, the CSS layer wrap); delivered from object
+        // storage, so refused without one. The store checks the bytes it writes again. A bootstrap
+        // plugin never carries it: a bootstrap run may have no object store (it may be a bootstrap
+        // plugin itself), and a required entry failing on that would stop the start.
+        if (ext?.section.client !== undefined) {
+            if (source.kind === "bootstrap") {
+                throw new ApiError("client.invalid", `Bootstrap plugin ${m.name} ships client code (extension.client), which a bootstrap plugin may not carry: its files are kept in object storage, which a bootstrap run may not have (the object store may be a bootstrap plugin itself); take ${m.name} out of bootstrap.json and import it into the catalog instead`);
+            }
+            checkClientFiles(ext.section.client, pkg.files);
+            this.files.assertAvailable();
+        }
         // A name live for another owner (an org's for the super admin; the platform's or another
         // org's for an org) -> 409 plugin.name_taken naming it (P3-14); the same owner adds a version
         await assertNameFree(this.db, m.name, owner?.orgId ?? null);
@@ -475,13 +500,16 @@ let PluginImport = class PluginImport {
                 .sort()
             : [];
         const mismatch = permissionsMismatch(opts.expect?.marketplace?.permissions, ext ? keys : undefined);
+        const manifest = normalizedManifest(pkg);
+        const replacements = manifest.suggestedAppearance?.replacements;
         const staged = {
             itemId,
             packageName,
             version,
             contentDigest: pkg.contentDigest,
             size: tgz.size,
-            manifest: normalizedManifest(pkg),
+            manifest,
+            ...(replacements !== undefined && { appearanceOrder: Object.keys(replacements) }),
             files: content.files.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
             ...(mismatch !== null && { permissionsMismatch: mismatch }),
             sourceFormat: format,
@@ -785,6 +813,22 @@ let PluginImport = class PluginImport {
         // Checked again before this upload claims anything (ruling P3-51)
         if (owner !== undefined)
             await assertPackageFree(t, staged.packageName, owner.orgId);
+        // The item's name lock and its live row before the extension's install lock: the global lock
+        // order is the item, then the install lock (ruling P3-50; ExtensionAdminOps.install locks the
+        // source item row before the install lock, an org deletion its items before it). Taken after
+        // the install lock instead, a confirmation of an org upload racing a replacement upload
+        // deadlocks (40P01).
+        const m = manifest;
+        await this.itemLock.lock(m.name);
+        // The scope the audit records: the review's for a new item, the item's own for a new version
+        // of a live item (which keeps its scope)
+        const existing = await t
+            .selectFrom("catalog_items")
+            .select(["id", "scope", "awaiting_confirmation", "package_name"])
+            .where("name", "=", m.name)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
         let now;
         let previous;
         if (reviewed) {
@@ -817,8 +861,6 @@ let PluginImport = class PluginImport {
                 previous = await this.approve(actor, review, staged, now, stored, opts);
             }
         }
-        const m = manifest;
-        await this.itemLock.lock(m.name);
         // Under the name's lock: the first confirm of a name wins, a later one of another owner is
         // refused naming it, before anything of it is written (P3-14)
         await assertNameFree(t, m.name, owner?.orgId ?? null);
@@ -826,15 +868,6 @@ let PluginImport = class PluginImport {
             await assertNameNotReserved(t, m.name);
             await this.resolveDependencies(m, owner);
         }
-        // The scope the audit records: the review's for a new item, the item's own for a new version
-        // of a live item (which keeps its scope)
-        const existing = await t
-            .selectFrom("catalog_items")
-            .select(["id", "scope", "awaiting_confirmation", "package_name"])
-            .where("name", "=", m.name)
-            .where("deleted_at", "is", null)
-            .forUpdate()
-            .executeTakeFirst();
         const actual = existing === undefined
             ? scope
             : {
@@ -879,6 +912,7 @@ let PluginImport = class PluginImport {
             version: staged.version,
             contentDigest: staged.contentDigest,
             manifest: m,
+            appearanceOrder: staged.appearanceOrder ?? null,
             listing: {
                 publisher: m.publisher,
                 description: pluginDescription(m.description).en,
@@ -1307,8 +1341,27 @@ let PluginImport = class PluginImport {
                 .executeTakeFirst());
         if (used !== undefined)
             return;
-        // extension_blobs (a PG-stored package) goes with the row (ON DELETE CASCADE)
+        const build = await t
+            .selectFrom("extension_client_builds")
+            .select("object_prefix")
+            .where("package_sha256", "=", sha)
+            .executeTakeFirst();
+        // extension_blobs (a PG-stored package) and extension_client_builds go with the row (ON
+        // DELETE CASCADE)
         await t.deleteFrom("extension_packages").where("sha256", "=", sha).execute();
+        if (build !== undefined) {
+            afterCommit(async () => {
+                try {
+                    await this.clientBuilds.deleteFiles(sha, build.object_prefix);
+                }
+                catch (err) {
+                    this.log.warn("cannot delete an expired org upload's client build objects", {
+                        sha256: sha,
+                        err,
+                    });
+                }
+            });
+        }
         // The object only once the row is gone for good: a failure leaves an unreferenced object
         // (harmless; a later upload of the same bytes rewrites it), never a row without its bytes
         if (pkg.blob_store === "object") {
@@ -1588,6 +1641,7 @@ let PluginImport = class PluginImport {
             warnings,
             reviewHash: extensionReviewHash(set, warnings),
             sensitive: permissions.some((g) => g.sensitive) || warnings.length > 0,
+            ...(pkg.section.client !== undefined && { client: reviewClient(pkg) }),
         };
     }
     async readStored(sha256) {
@@ -1654,7 +1708,8 @@ PluginImport = __decorate([
     __param(13, Inject(KERNEL_LOGGER)),
     __param(14, Inject(TransactionHost)),
     __param(15, Inject(PlatformComponents)),
-    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(17, Inject(ClientBuilds))
 ], PluginImport);
 export { PluginImport };
 /**
@@ -1751,6 +1806,27 @@ export function pluginReviewHash(r, files) {
     ]);
     return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
 }
+/** The client code of a read extension package for its review (sizes from the package's files). */
+function reviewClient(pkg) {
+    const c = pkg.section.client;
+    const sizes = new Map(pkg.files.map((f) => [f.path, f.size]));
+    const files = [
+        ...(c.entry !== undefined ? [c.entry] : []),
+        ...(c.styles ?? []),
+        ...(c.assets ?? []),
+    ].map((path) => {
+        // checkClientFiles ran first: every listed file is in the package
+        const size = sizes.get(path.slice(2));
+        if (size === undefined)
+            throw new Error(`client file ${path} is not in the package`);
+        return { path, size };
+    });
+    return {
+        files,
+        totalBytes: files.reduce((n, f) => n + f.size, 0),
+        apiVersion: c.apiVersion,
+    };
+}
 /**
  * A version change that is a downgrade (the imported version below the installed one) whose
  * version has migrations not run on this deployment -> `extension.downgrade_unsupported` (the same

package/dist/catalog/plugin-package.d.ts

@@ -16,9 +16,11 @@ export { LEGACY_FORMAT_MESSAGE, packagePath };
  */
 /**
  * Codes of {@link PluginPackageError}: `theme.invalid` / `theme.unreadable` when the package's only
- * problems are in its themes (themes spec §5: a failing theme refuses the whole plugin).
+ * problems are in its themes (themes spec §5: a failing theme refuses the whole plugin);
+ * `client.undeclared` for an `extension.client` section whose manifest lacks
+ * `permissions.client: true` (client extensions spec §5.4: client code is always reviewed).
  */
-export type PluginPackageErrorCode = "catalog.invalid_manifest" | "catalog.legacy_format" | "theme.invalid" | "theme.unreadable";
+export type PluginPackageErrorCode = "catalog.invalid_manifest" | "catalog.legacy_format" | "theme.invalid" | "theme.unreadable" | "client.undeclared";
 /** The problems of one theme of a refused plugin (English; `unreadable:` lines for readability). */
 export interface PluginThemeProblem {
     /** The theme id (the file's base name). */

package/dist/catalog/plugin-package.js

@@ -12,9 +12,11 @@ export class PluginPackageError extends Error {
     constructor(code, issues, themes) {
         super(code === "catalog.legacy_format"
             ? (issues[0] ?? LEGACY_FORMAT_MESSAGE)
-            : code === "theme.invalid" || code === "theme.unreadable"
-                ? `Theme ${themes?.[0]?.theme ?? "?"} ${code === "theme.invalid" ? "is invalid" : "is not readable"}: ${issues[0] ?? "unknown problem"}`
-                : `Invalid plugin package: ${issues[0] ?? "unknown problem"}`);
+            : code === "client.undeclared"
+                ? (issues[0] ?? code)
+                : code === "theme.invalid" || code === "theme.unreadable"
+                    ? `Theme ${themes?.[0]?.theme ?? "?"} ${code === "theme.invalid" ? "is invalid" : "is not readable"}: ${issues[0] ?? "unknown problem"}`
+                    : `Invalid plugin package: ${issues[0] ?? "unknown problem"}`);
         this.name = "PluginPackageError";
         this.code = code;
         this.issues = issues;
@@ -78,6 +80,27 @@ export function iconProblem(path, data) {
     return /<svg[\s>/]/i.test(text) ? undefined : `${path} is not an SVG document`;
 }
 /** package.json parsed, or undefined when it is not valid (only used to name a legacy package). */
+/**
+ * Client code the extension manifest does not declare (an `extension.client` section without
+ * `permissions.client: true`), read from the raw plugin.json before it is parsed, so the refusal
+ * names it (`client.undeclared`) instead of being one parse problem among others.
+ */
+function clientUndeclared(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const ext = isObj(raw) ? raw.extension : undefined;
+    if (!isObj(ext) || ext.client === undefined)
+        return undefined;
+    const perms = isObj(ext.manifest) ? ext.manifest.permissions : undefined;
+    if (isObj(perms) && perms.client === true)
+        return undefined;
+    return `${PLUGIN_MANIFEST_FILE}: extension.client ships client code, but the extension manifest does not declare permissions.client: true; client code must be declared so it is reviewed (capybara-plugin pack writes both)`;
+}
 const parsedOrUndefined = (data) => {
     try {
         return parsePackageJsonFile({ data });
@@ -201,6 +224,9 @@ export function readPluginFiles(files, opts) {
         const text = decode(manifestBytes);
         if (text === undefined)
             return invalid([`${PLUGIN_MANIFEST_FILE} is not valid UTF-8 text`]);
+        const undeclared = clientUndeclared(text);
+        if (undeclared !== undefined)
+            throw new PluginPackageError("client.undeclared", [undeclared]);
         const parsed = parsePluginManifest(text);
         if ("errors" in parsed) {
             return invalid(parsed.errors.map((e) => `${PLUGIN_MANIFEST_FILE}: ${e}`));

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

@@ -9,6 +9,10 @@ export declare const ChannelCreateSchema: z.ZodObject<{
         anonymous: "anonymous";
         bind: "bind";
     }>>;
+    inboundMode: z.ZodOptional<z.ZodEnum<{
+        long_connection: "long_connection";
+        webhook: "webhook";
+    }>>;
 }, z.core.$strict>;
 export declare const ChannelPatchSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;

package/dist/channels/channels.schemas.js

@@ -8,6 +8,8 @@ export const ChannelCreateSchema = z
     agentId: z.string().min(1).max(100),
     config: Config,
     unboundPolicy: Policy.optional(),
+    // default long_connection; webhook needs plugin support and channels.webhookBaseUrl (409)
+    inboundMode: z.enum(["long_connection", "webhook"]).optional(),
 })
     .strict();
 export const ChannelPatchSchema = z

package/dist/channels/connections.controller.d.ts

@@ -7,7 +7,7 @@ import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ChannelCreateSchema as CreateBody, ChannelGuideAckSchema as GuideAckBody, ChannelPatchSchema as PatchBody } from "./channels.schemas.js";
-import { ChannelConnections, type ChannelConnectionView } from "./connections.service.js";
+import { ChannelConnections, type ChannelConnectionView, type ChannelInboundInfo } from "./connections.service.js";
 /**
  * A connection as the org's pages show it: its plugin's display name (null when it has none) and
  * the URL of its plugin's icon on the org's catalog route (null without one, or when the org may
@@ -36,13 +36,15 @@ export declare class ChannelConnectionsController {
         channels: ChannelConnectionPage[];
     }>;
     /**
-     * The connection form's JSON Schema, and where the plugin's setup guide is (`guide`, null when
-     * the plugin has none the org may see): 新建渠道 shows it once the plugin is picked.
+     * The connection form's JSON Schema, where the plugin's setup guide is (`guide`, null when the
+     * plugin has none the org may see): 新建渠道 shows it once the plugin is picked; and whether its
+     * connections can use webhook inbound (`inbound`, channel inbound mode fields spec §4).
      */
     schema(org: OrgContext, plugin: string): Promise<{
         plugin: string;
         schema: JsonSchema;
         guide: Omit<SetupGuideRef, "version"> | null;
+        inbound: ChannelInboundInfo;
     }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
         channel: ChannelConnectionPage;

package/dist/channels/connections.controller.js

@@ -16,7 +16,7 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { ChannelCreateSchema as CreateBody, ChannelGuideAckSchema as GuideAckBody, ChannelPatchSchema as PatchBody, } from "./channels.schemas.js";
-import { ChannelConnections } from "./connections.service.js";
+import { ChannelConnections, } from "./connections.service.js";
 class ChannelCreateBody extends createZodDto(CreateBody, "ChannelCreateBody") {
 }
 class ChannelPatchBody extends createZodDto(PatchBody, "ChannelPatchBody") {
@@ -62,13 +62,15 @@ let ChannelConnectionsController = class ChannelConnectionsController {
         return { channels: await this.withPlugins(org, await this.channels.list(org.orgId)) };
     }
     /**
-     * The connection form's JSON Schema, and where the plugin's setup guide is (`guide`, null when
-     * the plugin has none the org may see): 新建渠道 shows it once the plugin is picked.
+     * The connection form's JSON Schema, where the plugin's setup guide is (`guide`, null when the
+     * plugin has none the org may see): 新建渠道 shows it once the plugin is picked; and whether its
+     * connections can use webhook inbound (`inbound`, channel inbound mode fields spec §4).
      */
     async schema(org, plugin) {
         const schema = this.channels.jsonSchema(plugin);
+        const inbound = this.channels.inboundInfo(plugin);
         const g = (await this.guides.channelGuides([plugin], org)).get(plugin);
-        return { plugin, schema, guide: g ? { itemId: g.itemId, guideId: g.guideId } : null };
+        return { plugin, schema, guide: g ? { itemId: g.itemId, guideId: g.guideId } : null, inbound };
     }
     async create(principal, org, body) {
         const p = requireUser(principal);

package/dist/channels/connections.service.d.ts

@@ -15,6 +15,11 @@ import { OrgLock } from "../orgs/org-lock.js";
 import type { OrgRole } from "../orgs/roles.js";
 import { ChannelJobs } from "./jobs.js";
 import type { ChannelLocale } from "./phrases.js";
+/**
+ * A public https address: https, and the host is not loopback, a private / link-local / reserved
+ * IP, `localhost`, `*.localhost`, `*.local`, `*.internal` or a single label (no DNS lookup).
+ */
+export declare function isPublicHttpsUrl(url: string): boolean;
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
 export declare const connectionSecretKey: (connectionId: string) => string;
 /**
@@ -82,6 +87,18 @@ export interface CreateChannelInput {
     agentId: string;
     config: Record<string, unknown>;
     unboundPolicy?: UnboundPolicy | undefined;
+    /** Default `long_connection`; `webhook` needs plugin support and `channels.webhookBaseUrl`. */
+    inboundMode?: InboundMode | undefined;
+}
+/**
+ * Whether a channel plugin's connections can use webhook inbound (channel inbound mode fields spec
+ * §4): the plugin implements `Channel.webhook`; the kernel accepts webhook mode (a usable
+ * `channels.webhookBaseUrl`); and that base URL is a public https address.
+ */
+export interface ChannelInboundInfo {
+    webhookSupported: boolean;
+    webhookAvailable: boolean;
+    webhookPublic: boolean;
 }
 /** `config` 里的密钥字段：缺省 = 保留原值、`null` = 清除、其他值 = 新值（同组织插件配置）。 */
 export interface UpdateChannelInput {
@@ -163,6 +180,15 @@ export declare class ChannelConnections implements OnApplicationShutdown {
      * `channels.webhookBaseUrl` (otherwise there is no URL to give the platform): 409 otherwise.
      */
     private assertWebhookAvailable;
+    /**
+     * The fields the inbound mode requires (`x-ui.inboundModes`, channel inbound mode fields spec
+     * §3) must have a value in `full` (the parsed config, stored secrets included): 400
+     * `extension.config_invalid` with one issue per missing field otherwise. A plugin without the
+     * hint passes.
+     */
+    private assertModeFields;
+    /** Whether the plugin's connections can use webhook inbound (spec §4); `extension.not_found`. */
+    inboundInfo(plugin: string): ChannelInboundInfo;
     private viewOf;
     private live;
     list(orgId: string): Promise<ChannelConnectionView[]>;

package/dist/channels/connections.service.js

@@ -8,7 +8,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { CHANNEL_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { isIP } from "node:net";
+import { CHANNEL_EXTENSION_POINT, missingInboundModeFields, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { configFields, getPath, secretScalars, secretValues } from "../config/fields.js";
@@ -28,11 +29,35 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { KERNEL_BUS, KERNEL_LOGGER, KEYRING, REDIS } from "../infra/tokens.js";
 import { createRedactor } from "../log.js";
+import { isForbiddenAddress, isLoopbackHost, normalizeHost } from "../net/public-address.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
 import { adaptToFeatures } from "./features.js";
 import { ChannelJobs } from "./jobs.js";
 import { webhookBase, webhookUrlOf } from "./webhook-url.js";
+/**
+ * A public https address: https, and the host is not loopback, a private / link-local / reserved
+ * IP, `localhost`, `*.localhost`, `*.local`, `*.internal` or a single label (no DNS lookup).
+ */
+export function isPublicHttpsUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol !== "https:")
+        return false;
+    const host = normalizeHost(u.hostname);
+    if (isLoopbackHost(host))
+        return false;
+    if (isIP(host) !== 0)
+        return !isForbiddenAddress(host);
+    if (!host.includes("."))
+        return false;
+    return ![".localhost", ".local", ".internal"].some((s) => host.endsWith(s));
+}
 /** 内核 secrets 命名空间（插件名不能取 `kernel`）。 */
 const SECRETS_NAMESPACE = "kernel";
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
@@ -305,6 +330,38 @@ let ChannelConnections = class ChannelConnections {
             throw new ApiError("channel.webhook_unavailable", "Webhook inbound needs channels.webhookBaseUrl to be configured");
         }
     }
+    /**
+     * The fields the inbound mode requires (`x-ui.inboundModes`, channel inbound mode fields spec
+     * §3) must have a value in `full` (the parsed config, stored secrets included): 400
+     * `extension.config_invalid` with one issue per missing field otherwise. A plugin without the
+     * hint passes.
+     */
+    assertModeFields(plugin, schema, mode, full) {
+        const js = this.formSchema(plugin, this.versionOf(plugin), schema)?.schema;
+        if (js === undefined)
+            return;
+        const missing = missingInboundModeFields(js, mode, (field) => {
+            const v = getPath(full, field);
+            return v !== undefined && v !== null && v !== "";
+        });
+        if (missing.length === 0)
+            return;
+        throw new ApiError("extension.config_invalid", `Invalid channel connection config for extension ${plugin}`, missing.map((field) => ({
+            path: field,
+            segments: [field],
+            message: `required in ${mode} mode`,
+        })));
+    }
+    /** Whether the plugin's connections can use webhook inbound (spec §4); `extension.not_found`. */
+    inboundInfo(plugin) {
+        const webhookSupported = this.channel(plugin).webhook !== undefined;
+        const base = this.webhookBase();
+        return {
+            webhookSupported,
+            webhookAvailable: webhookSupported && base !== undefined,
+            webhookPublic: webhookSupported && base !== undefined && isPublicHttpsUrl(base),
+        };
+    }
     async viewOf(row) {
         return this.view(row, new Set(Object.keys(await this.readSecrets(row.org_id, row.id))));
     }
@@ -331,14 +388,16 @@ let ChannelConnections = class ChannelConnections {
         await this.assertEnabled(orgId, input.plugin);
         const schema = channel.connectionSchema;
         const full = this.parse(input.plugin, schema, input.config);
+        const mode = input.inboundMode ?? "long_connection";
+        if (mode === "webhook")
+            this.assertWebhookAvailable(input.plugin);
+        this.assertModeFields(input.plugin, schema, mode, full);
         await this.assertAgent(orgId, input.agentId);
         const verified = await this.verify(channel, full);
         const id = randomUUID();
         const { plain, secrets } = split(schema, full);
-        // the guide the 新建渠道 page showed: the plugin's current one, for the default mode
-        const guideAck = await this.guides.currentAck(input.plugin, "channel-connection", {
-            mode: "long_connection",
-        });
+        // the guide the 新建渠道 page showed: the plugin's current one, for the mode picked there
+        const guideAck = await this.guides.currentAck(input.plugin, "channel-connection", { mode });
         const row = await this.insertIn({
             orgId,
             id,
@@ -372,6 +431,7 @@ let ChannelConnections = class ChannelConnections {
             agent_id: input.agentId,
             config: JSON.stringify(a.plain),
             unbound_policy: input.unboundPolicy ?? "bind",
+            inbound_mode: input.inboundMode ?? "long_connection",
             bot_user_id: a.verified.botUserId,
             tenant_id: a.verified.tenantId,
             guide_ack: a.guideAck === null ? null : JSON.stringify(a.guideAck),
@@ -385,7 +445,11 @@ let ChannelConnections = class ChannelConnections {
             orgId,
             action: "channel.created",
             target: id,
-            detail: { plugin: input.plugin, agentId: input.agentId },
+            detail: {
+                plugin: input.plugin,
+                agentId: input.agentId,
+                inboundMode: input.inboundMode ?? "long_connection",
+            },
         });
         return inserted;
     }
@@ -437,6 +501,15 @@ let ChannelConnections = class ChannelConnections {
         const modeChanged = patch.inboundMode !== undefined && patch.inboundMode !== current.inbound_mode;
         if (modeChanged && patch.inboundMode === "webhook")
             this.assertWebhookAvailable(current.plugin);
+        if (rotated || modeChanged) {
+            // the fields the effective mode requires (spec §3): the new config, else the stored one
+            const schema = this.channel(current.plugin).connectionSchema;
+            const full = rotated?.full ?? {
+                ...(current.config ?? {}),
+                ...(await this.readSecrets(orgId, id)),
+            };
+            this.assertModeFields(current.plugin, schema, patch.inboundMode ?? current.inbound_mode, full);
+        }
         if (patch.agentId !== undefined)
             await this.assertAgent(orgId, patch.agentId);
         // A mode switch sets the platform app up for the new mode: the guide of that mode is the one