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

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

@@ -188,7 +188,7 @@ export declare function headsToResolve(entries: readonly MarketplaceEntry[], imp
 /** The host versions (an entry's `minKernel` is judged against them). */
 export declare const HOST_VERSIONS: {
     readonly kernel: string;
-    readonly sdk: "0.1.0-rc.11";
+    readonly sdk: "0.1.0-rc.12";
 };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;

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

package/dist/extensions/guide-places.d.ts

@@ -4,8 +4,10 @@ import type { KernelDb } from "../infra/database/kernel-db.js";
 import type { OrgAction } from "../orgs/roles.js";
 /** Why a known variable has no value: what the web and the `Platform` tool tell the reader. */
 export type UnresolvedReason = 
-/** The target is not saved yet (the webhook URL, a connection name nobody typed). */
+/** The target is not saved yet (the webhook URL). */
 "not_saved"
+/** No name typed yet on the new target's form (a connection name on 新建渠道). */
+ | "no_name"
 /** `http.publicUrl` is not set (the URLs built from it). */
  | "public_url"
 /** `channels.webhookBaseUrl` is not set or unusable. */

package/dist/extensions/guide-places.js

@@ -58,7 +58,7 @@ export async function resolvePlace(ctx) {
         const typed = ctx.query.name?.trim();
         values.connectionName =
             connection?.name ?? (typed === undefined || typed === "" ? null : typed);
-        reasons.connectionName = "not_saved";
+        reasons.connectionName = "no_name";
         if (connection !== undefined) {
             target = { kind: "channel-connection", id: connection.id };
             storedMode = connection.inbound_mode;

package/dist/extensions/permission-view.d.ts

@@ -12,11 +12,11 @@ import type { ExtensionSource } from "./sources.js";
 export declare function reviewHash(set: PermissionSet, warnings?: readonly PackageWarning[]): string;
 /** 权限清单展示用的一组：按类别分组，`sensitive` 标出需要管理员特别留意的类别。 */
 export interface PermissionGroup {
-    category: "provides" | "requires" | "optional" | "config" | "tables" | "secrets" | "storage" | "http" | "publicRoutes" | "tools" | "hooks" | "models" | "network" | "ui" | "client";
+    category: "provides" | "requires" | "optional" | "config" | "tables" | "secrets" | "storage" | "http" | "publicRoutes" | "tools" | "hooks" | "models" | "network" | "ui" | "components" | "client";
     /**
-     * Sensitive category: secrets, public routes, tools, hooks, client code; also the "provides" group
-     * when it holds one of {@link SENSITIVE_EXTENSION_POINTS}, and the "UI" group when it holds an
-     * embedded app (embed: the extension's own page in an iframe) or a client component.
+     * Sensitive category: secrets, public routes, tools, hooks, client components, client code; also
+     * the "provides" group when it holds one of {@link SENSITIVE_EXTENSION_POINTS}, and the "UI" group
+     * (views and embeds) when it holds an embedded app (embed: the extension's own page in an iframe).
      */
     sensitive: boolean;
     items: string[];

package/dist/extensions/permission-view.js

@@ -38,6 +38,7 @@ const ALWAYS_SENSITIVE = new Set([
     "publicRoutes",
     "tools",
     "hooks",
+    "components",
     "client",
 ]);
 const CATEGORY_REASON = {
@@ -45,13 +46,14 @@ const CATEGORY_REASON = {
     publicRoutes: "public_routes",
     tools: "tools",
     hooks: "hooks",
+    components: "ui_component",
     client: "client_code",
 };
 /**
  * Why an item in a category is sensitive (undefined when it is not; shared by the grouped list, the
  * per-item `added` and the CLI markers): secrets, public routes, tools, hooks and client code are
- * always sensitive; {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`)
- * and client components (`component:<id>`) in "UI".
+ * always sensitive, and so are client components (their own group, items are the component ids);
+ * {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`) in "UI".
  */
 function itemReason(category, item) {
     // storage 不算敏感：ctx.storage 的键由内核加前缀 `plugins/<插件>/<orgId>/`，插件只能读写自己的前缀
@@ -63,8 +65,6 @@ function itemReason(category, item) {
     if (category === "ui") {
         if (item.startsWith("embed:"))
             return "ui_embed";
-        if (item.startsWith("component:"))
-            return "ui_component";
         return undefined;
     }
     return ALWAYS_SENSITIVE.has(category) ? CATEGORY_REASON[category] : undefined;
@@ -89,7 +89,7 @@ function keyItem(key) {
         ["permissions.hooks:", "hooks", ""],
         ["permissions.hooks.policy:", "hooks", "policy:"],
         ["ui.embed:", "ui", "embed:"],
-        [UI_COMPONENT_KEY_PREFIX, "ui", "component:"],
+        [UI_COMPONENT_KEY_PREFIX, "components", ""],
         ["ui.view:", "ui", "view:"],
     ];
     for (const [prefix, category, itemPrefix] of table) {
@@ -162,12 +162,9 @@ export function permissionGroups(set) {
         { category: "network", items: p.network },
         {
             category: "ui",
-            items: [
-                ...ui.views.map((v) => `view:${v}`),
-                ...ui.embeds.map((e) => `embed:${e}`),
-                ...components.map((c) => `component:${c}`),
-            ],
+            items: [...ui.views.map((v) => `view:${v}`), ...ui.embeds.map((e) => `embed:${e}`)],
         },
+        { category: "components", items: components },
         { category: "client", items: p.client === true ? [CLIENT_ITEM] : [] },
     ];
     return groups

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.15",
+  "version": "0.1.0-rc.16",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -65,7 +65,7 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.11"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.12"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
@@ -74,7 +74,7 @@
     "@types/ws": "^8.18.2",
     "@types/yauzl": "3.4.0",
     "ws": "^8.22.0",
-    "@capybara-hq/testing": "0.1.0-rc.14"
+    "@capybara-hq/testing": "0.1.0-rc.15"
   },
   "scripts": {
     "build": "tsc -b"