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

package/dist/channels/threads.d.ts

@@ -1,11 +1,32 @@
 import type { ChannelTarget } from "@capybara-hq/plugin-sdk";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { XactLock } from "../infra/database/xact-lock.js";
 /**
- * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
- * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
- * 跨副本并发首次创建用事务级咨询锁串行化，只建一个账号。
+ * The lock of an org's anonymous guest account (one provider per transaction-scoped lock):
+ * serializes the first creation across replicas, so only one account is created. Joins the caller's
+ * transaction (`mandatory`), which holds it until it ends.
  */
-export declare function ensureAnonymousGuest(db: KernelDb, orgId: string): Promise<string>;
+export declare class AnonymousGuestLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(orgId: string): Promise<void>;
+}
+/** 组织的匿名访客账号（渠道连接的未绑定策略 `anonymous`）。 */
+export declare class AnonymousGuests {
+    private readonly db;
+    private readonly guestLock;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, guestLock: AnonymousGuestLock, txHost: TransactionHost);
+    /**
+     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
+     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
+     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     */
+    ensure(orgId: string): Promise<string>;
+}
 /** 一条 IM 话题的定位：连接 + chat + 话题键 + 账号（匿名为 null）。 */
 export interface ThreadKey {
     connectionId: string;
@@ -19,11 +40,16 @@ export interface ThreadKey {
  */
 export declare function threadKeyOf(target: ChannelTarget, senderExternalId: string, messageId: string): string;
 /** 未归档的话题行对应的会话；没有返回 undefined。 */
-export declare function findThread(db: KernelDb, k: ThreadKey): Promise<string | undefined>;
+export declare function findThread(db: KernelSchemaDb, k: ThreadKey): Promise<string | undefined>;
 /**
  * 记下话题 → 会话；同一话题已有未归档的行（并发的另一条消息抢先建了）时不写，返回已有的会话 id。
  * 返回实际生效的会话 id。
  */
-export declare function insertThread(db: KernelDb, k: ThreadKey, conversationId: string): Promise<string>;
+export declare function insertThread(db: KernelSchemaDb, k: ThreadKey, conversationId: string): Promise<string>;
 /** 私聊 `/new`：归档当前话题行（下一条消息新建对话）。返回是否归档了一行。 */
-export declare function archiveThread(db: KernelDb, k: ThreadKey): Promise<boolean>;
+export declare function archiveThread(db: KernelSchemaDb, k: ThreadKey): Promise<boolean>;
+/**
+ * Drops a conversation's channel bindings (its thread rows and its delivery target), so a deleted
+ * conversation neither receives inbound messages nor posts to the chat any more.
+ */
+export declare function unbindConversation(db: KernelSchemaDb, conversationId: string): Promise<void>;

package/dist/channels/threads.js

@@ -1,19 +1,67 @@
+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 { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { audit } from "../identity/audit.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";
+import { XactLock } from "../infra/database/xact-lock.js";
 /** 匿名访客账号的显示名。 */
 const ANONYMOUS_DISPLAY_NAME = "Anonymous guest";
 /** 匿名访客成员关系的来源标记（通讯录同步只撤销 `directory:*`，不会碰它）。 */
 const ANONYMOUS_MEMBERSHIP_SOURCE = "anonymous";
 /**
- * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
- * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
- * 跨副本并发首次创建用事务级咨询锁串行化，只建一个账号。
+ * The lock of an org's anonymous guest account (one provider per transaction-scoped lock):
+ * serializes the first creation across replicas, so only one account is created. Joins the caller's
+ * transaction (`mandatory`), which holds it until it ends.
  */
-export async function ensureAnonymousGuest(db, orgId) {
-    return db.transaction().execute(async (t) => {
-        await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.anonymous:${orgId}`}))`.execute(t);
-        const existing = await t
+let AnonymousGuestLock = class AnonymousGuestLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(orgId) {
+        await this.xactLock.lock(`capybara.anonymous:${orgId}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AnonymousGuestLock.prototype, "lock", null);
+AnonymousGuestLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], AnonymousGuestLock);
+export { AnonymousGuestLock };
+/** 组织的匿名访客账号（渠道连接的未绑定策略 `anonymous`）。 */
+let AnonymousGuests = class AnonymousGuests {
+    db;
+    guestLock;
+    txHost;
+    constructor(db, guestLock, txHost) {
+        this.db = db;
+        this.guestLock = guestLock;
+        this.txHost = txHost;
+    }
+    /**
+     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
+     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
+     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     */
+    async ensure(orgId) {
+        await this.guestLock.lock(orgId);
+        const existing = await this.db
             .selectFrom("org_anonymous_accounts")
             .select("account_id")
             .where("org_id", "=", orgId)
@@ -21,22 +69,22 @@ export async function ensureAnonymousGuest(db, orgId) {
         let accountId = existing?.account_id;
         if (accountId === undefined) {
             accountId = randomUUID();
-            await t
+            await this.db
                 .insertInto("accounts")
                 .values({ id: accountId, display_name: ANONYMOUS_DISPLAY_NAME, email: null })
                 .execute();
-            await t
+            await this.db
                 .insertInto("org_anonymous_accounts")
                 .values({ org_id: orgId, account_id: accountId })
                 .execute();
-            await audit(t, {
+            await audit(this.db.db, {
                 orgId,
                 action: "account.created",
                 target: accountId,
                 detail: { anonymousGuest: true },
             });
         }
-        await t
+        await this.db
             .insertInto("memberships")
             .values({
             org_id: orgId,
@@ -47,8 +95,18 @@ export async function ensureAnonymousGuest(db, orgId) {
             .onConflict((oc) => oc.columns(["org_id", "account_id"]).doNothing())
             .execute();
         return accountId;
-    });
-}
+    }
+};
+__decorate([
+    Transactional()
+], AnonymousGuests.prototype, "ensure", null);
+AnonymousGuests = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AnonymousGuestLock)),
+    __param(2, Inject(TransactionHost))
+], AnonymousGuests);
+export { AnonymousGuests };
 /**
  * 话题键：私聊 `dm:<externalId>`；群聊用平台话题 id，消息不在话题里（开启新话题）时用该消息 id——
  * 机器人回复在以它为根的话题里，后续消息的 threadId 就是它，于是落到同一个对话。
@@ -102,3 +160,11 @@ export async function archiveThread(db, k) {
         .executeTakeFirst();
     return r.numUpdatedRows > 0n;
 }
+/**
+ * Drops a conversation's channel bindings (its thread rows and its delivery target), so a deleted
+ * conversation neither receives inbound messages nor posts to the chat any more.
+ */
+export async function unbindConversation(db, conversationId) {
+    await db.deleteFrom("channel_threads").where("conversation_id", "=", conversationId).execute();
+    await db.deleteFrom("channel_deliveries").where("conversation_id", "=", conversationId).execute();
+}

package/dist/channels/webhook.d.ts

@@ -1,6 +1,6 @@
 import type { ChannelWebhookRequest, ChannelWebhookResponse, Logger } from "@capybara-hq/plugin-sdk";
-import type { ChannelConnections } from "./connections.service.js";
-import type { ChannelInbound } from "./inbound.js";
+import { ChannelConnections } from "./connections.service.js";
+import { ChannelInbound } from "./inbound.js";
 /**
  * Deadline of one webhook request: connection lookups, the plugin's `webhook.handle` and handing
  * its events to `onEvent` (platform ack deadlines are a few seconds). Past it the kernel answers 503.
@@ -8,6 +8,15 @@ import type { ChannelInbound } from "./inbound.js";
 export declare const WEBHOOK_HANDLE_TIMEOUT_MS = 10000;
 /** How long a connection's decrypted runtime (plugin + config) is reused across requests. */
 export declare const WEBHOOK_RUNTIME_CACHE_MS = 5000;
+/** The timings of {@link ChannelWebhooks}. */
+export interface ChannelWebhookTimings {
+    /** The deadline of one request (ms), default {@link WEBHOOK_HANDLE_TIMEOUT_MS}. */
+    handleTimeoutMs: number;
+    /** How long a connection's runtime is reused (ms; 0 disables the cache), default {@link WEBHOOK_RUNTIME_CACHE_MS}. */
+    runtimeCacheMs: number;
+}
+/** Optional provider: {@link ChannelWebhookTimings} that replace some defaults (tests). */
+export declare const CHANNEL_WEBHOOK_TIMINGS: unique symbol;
 /** Most connections whose runtime is cached in one process. */
 export declare const WEBHOOK_RUNTIME_CACHE_MAX = 1000;
 /**
@@ -15,17 +24,8 @@ export declare const WEBHOOK_RUNTIME_CACHE_MAX = 1000;
  * be rendered or sniffed by a browser).
  */
 export declare const WEBHOOK_SECURITY_HEADERS: Readonly<Record<string, string>>;
-export interface ChannelWebhooksDeps {
-    connections: Pick<ChannelConnections, "row" | "runtime">;
-    inbound: Pick<ChannelInbound, "onEvent">;
-    log: Pick<Logger, "warn">;
-    /** Defaults to {@link WEBHOOK_HANDLE_TIMEOUT_MS}. */
-    handleTimeoutMs?: number;
-    /** Defaults to {@link WEBHOOK_RUNTIME_CACHE_MS}; 0 disables the cache. */
-    runtimeCacheMs?: number;
-}
 /**
- * Channel webhook inbound (F8 / F9), framework free. The gateway route
+ * Channel webhook inbound (F8 / F9), gateway role only. The gateway route
  * `POST /channels/webhook/:connectionId` hands every request here; the kernel applies no auth, so
  * everything a request can do goes through the plugin's `webhook.handle`, which verifies the
  * signature, decrypts and checks timestamps:
@@ -57,11 +57,17 @@ export interface ChannelWebhooksDeps {
  * counter keeps a fetch that started before `invalidateAll` from storing the old plugin instance.
  */
 export declare class ChannelWebhooks {
-    private readonly deps;
+    private readonly connections;
+    private readonly inbound;
+    private readonly log;
     private readonly runtimes;
     /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
     private generation;
-    constructor(deps: ChannelWebhooksDeps);
+    /** The deadline of one request. */
+    private readonly handleTimeoutMs;
+    /** How long a connection's runtime is reused; 0 disables the cache. */
+    private readonly runtimeCacheMs;
+    constructor(connections: Pick<ChannelConnections, "row" | "runtime">, inbound: Pick<ChannelInbound, "onEvent">, log: Pick<Logger, "warn">, timings?: Partial<ChannelWebhookTimings>);
     /** Drops the cached runtime of one connection (on `channel.changed`). */
     invalidate(connectionId: string): void;
     /** Drops every cached runtime (a plugin was replaced, revoked or reloaded). */

package/dist/channels/webhook.js

@@ -1,5 +1,18 @@
+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, Optional } from "@nestjs/common";
 import { ApiError, errorBody } from "../errors.js";
 import { ExtensionUnloadedError } from "../extensions/inflight.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ChannelConnections } from "./connections.service.js";
+import { ChannelInbound } from "./inbound.js";
 /**
  * Deadline of one webhook request: connection lookups, the plugin's `webhook.handle` and handing
  * its events to `onEvent` (platform ack deadlines are a few seconds). Past it the kernel answers 503.
@@ -7,6 +20,8 @@ import { ExtensionUnloadedError } from "../extensions/inflight.js";
 export const WEBHOOK_HANDLE_TIMEOUT_MS = 10_000;
 /** How long a connection's decrypted runtime (plugin + config) is reused across requests. */
 export const WEBHOOK_RUNTIME_CACHE_MS = 5_000;
+/** Optional provider: {@link ChannelWebhookTimings} that replace some defaults (tests). */
+export const CHANNEL_WEBHOOK_TIMINGS = Symbol("CHANNEL_WEBHOOK_TIMINGS");
 /** Most connections whose runtime is cached in one process. */
 export const WEBHOOK_RUNTIME_CACHE_MAX = 1_000;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -60,7 +75,7 @@ function raceAbort(p, signal) {
     });
 }
 /**
- * Channel webhook inbound (F8 / F9), framework free. The gateway route
+ * Channel webhook inbound (F8 / F9), gateway role only. The gateway route
  * `POST /channels/webhook/:connectionId` hands every request here; the kernel applies no auth, so
  * everything a request can do goes through the plugin's `webhook.handle`, which verifies the
  * signature, decrypts and checks timestamps:
@@ -91,13 +106,23 @@ function raceAbort(p, signal) {
  * mode switch, deletion…) and {@link invalidateAll} when a plugin instance changes; a generation
  * counter keeps a fetch that started before `invalidateAll` from storing the old plugin instance.
  */
-export class ChannelWebhooks {
-    deps;
+let ChannelWebhooks = class ChannelWebhooks {
+    connections;
+    inbound;
+    log;
     runtimes = new Map();
     /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
     generation = 0;
-    constructor(deps) {
-        this.deps = deps;
+    /** The deadline of one request. */
+    handleTimeoutMs;
+    /** How long a connection's runtime is reused; 0 disables the cache. */
+    runtimeCacheMs;
+    constructor(connections, inbound, log, timings = {}) {
+        this.connections = connections;
+        this.inbound = inbound;
+        this.log = log;
+        this.handleTimeoutMs = timings.handleTimeoutMs ?? WEBHOOK_HANDLE_TIMEOUT_MS;
+        this.runtimeCacheMs = timings.runtimeCacheMs ?? WEBHOOK_RUNTIME_CACHE_MS;
     }
     /** Drops the cached runtime of one connection (on `channel.changed`). */
     invalidate(connectionId) {
@@ -112,13 +137,13 @@ export class ChannelWebhooks {
         return secure(await this.respond(connectionId, request, signal));
     }
     async runtime(connectionId, deadline) {
-        const ttl = this.deps.runtimeCacheMs ?? WEBHOOK_RUNTIME_CACHE_MS;
+        const ttl = this.runtimeCacheMs;
         const now = Date.now();
         const hit = this.runtimes.get(connectionId);
         if (hit && hit.expiresAt > now)
             return hit.value;
         const generation = this.generation;
-        const value = await raceAbort(this.deps.connections.runtime(connectionId), deadline);
+        const value = await raceAbort(this.connections.runtime(connectionId), deadline);
         // A plugin instance changed while fetching: use the value once, keep no stale instance
         if (ttl > 0 && generation === this.generation) {
             this.runtimes.delete(connectionId);
@@ -137,22 +162,19 @@ export class ChannelWebhooks {
             return notFound();
         // One deadline for the whole request (DB lookups, handle, onEvent); also aborts when the
         // platform hangs up
-        const deadline = AbortSignal.any([
-            signal,
-            AbortSignal.timeout(this.deps.handleTimeoutMs ?? WEBHOOK_HANDLE_TIMEOUT_MS),
-        ]);
+        const deadline = AbortSignal.any([signal, AbortSignal.timeout(this.handleTimeoutMs)]);
         try {
             return await this.respondBefore(connectionId, request, deadline);
         }
         catch (err) {
             if (!(err instanceof WebhookDeadline))
                 throw err;
-            this.deps.log.warn("channel webhook timed out; the platform will retry", { connectionId });
+            this.log.warn("channel webhook timed out; the platform will retry", { connectionId });
             return retryLater();
         }
     }
     async respondBefore(connectionId, request, deadline) {
-        const row = await raceAbort(this.deps.connections.row(connectionId), deadline);
+        const row = await raceAbort(this.connections.row(connectionId), deadline);
         if (row === undefined ||
             row.inboundMode !== "webhook" ||
             row.status !== "active" ||
@@ -171,7 +193,7 @@ export class ChannelWebhooks {
                 (err.code === "channel.not_found" || err.code === "extension.not_enabled")) {
                 return notFound();
             }
-            this.deps.log.warn("channel webhook cannot load its connection", {
+            this.log.warn("channel webhook cannot load its connection", {
                 connectionId,
                 code: err instanceof ApiError ? err.code : undefined,
             });
@@ -200,13 +222,13 @@ export class ChannelWebhooks {
         }
         catch (err) {
             if (err instanceof WebhookDeadline) {
-                this.deps.log.warn("channel webhook handler timed out; the platform will retry", {
+                this.log.warn("channel webhook handler timed out; the platform will retry", {
                     connectionId,
                 });
                 return retryLater();
             }
             // The kernel log redacts the connection's secrets (runtime() registered them)
-            this.deps.log.warn("channel webhook handler failed", { connectionId, err });
+            this.log.warn("channel webhook handler failed", { connectionId, err });
             return jsonError(500, "internal", "Internal error");
         }
         finally {
@@ -223,10 +245,10 @@ export class ChannelWebhooks {
                     break;
                 for (const e of events) {
                     try {
-                        await raceAbort(this.deps.inbound.onEvent(connectionId, e), deadline);
+                        await raceAbort(this.inbound.onEvent(connectionId, e), deadline);
                     }
                     catch (err) {
-                        this.deps.log.warn("channel webhook event not accepted; the platform will retry", {
+                        this.log.warn("channel webhook event not accepted; the platform will retry", {
                             connectionId,
                             ...(err instanceof WebhookDeadline ? { timedOut: true } : { err }),
                         });
@@ -236,10 +258,19 @@ export class ChannelWebhooks {
                 return sanitize(result.ack);
             }
         }
-        this.deps.log.warn("channel webhook handler returned an invalid result", { connectionId });
+        this.log.warn("channel webhook handler returned an invalid result", { connectionId });
         return jsonError(500, "internal", "Internal error");
     }
-}
+};
+ChannelWebhooks = __decorate([
+    Injectable(),
+    __param(0, Inject(ChannelConnections)),
+    __param(1, Inject(ChannelInbound)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Optional()),
+    __param(3, Inject(CHANNEL_WEBHOOK_TIMINGS))
+], ChannelWebhooks);
+export { ChannelWebhooks };
 /** Generic codes for the statuses a plugin may reject with (same as the HTTP error filter's). */
 const REJECT_CODES = { 400: "validation_failed", 401: "auth.required", 403: "forbidden" };
 function rejected(status) {

package/dist/config/docs.js

@@ -63,7 +63,9 @@ export function renderConfigDocs(schema) {
         // body and package upload limits), apps/web/server.mjs (PORT / CAPYBARA_WEB_HOST) and
         // apps/web/src/dev/catalog/routes.tsx (CAPYBARA_DEV_UI); change this text together with them.
         // CAPYBARA_WEB_TRUST_PROXY: apps/web/src/lib/peer.ts; CAPYBARA_WEB_SHUTDOWN_GRACE_MS: apps/web/server.mjs.
+        // CAPYBARA_WEB_KEEP_ALIVE_TIMEOUT_MS: apps/web/src/lib/keep-alive.ts.
         // CAPYBARA_WEB_OBJECT_STORE_*: apps/web/src/lib/object-store-proxy.ts.
+        // CAPYBARA_WEB_GATEWAY_URL: apps/web/src/lib/device-connect-proxy.ts.
         "## Web tier (apps/web) environment variables",
         "",
         "The web tier is a separate process (started through `apps/web/server.mjs`); it does not read the kernel config and only honors the following environment variables:",
@@ -74,11 +76,13 @@ export function renderConfigDocs(schema) {
         "| `PORT` / `CAPYBARA_WEB_HOST` | The web tier's listen port (default 3000) and address |",
         "| `CAPYBARA_WEB_TRUST_PROXY` | Proxies in front of the web tier (TLS proxy, load balancer) trusted to report the client address in `X-Forwarded-For`: a hop count (`1` = the nearest proxy) or a list of IPs / CIDRs, comma-separated or a JSON array, in the grammar of `http.trustProxy` (dotted netmasks, `loopback` / `linklocal` / `uniquelocal`; a range that trusts every address such as `/0` is refused; no `true` / `false`). Unset (default) trusts nothing: the socket peer is the client, so behind a proxy every user shares the proxy's address for login rate limiting. A hop count is only safe when the web tier is reachable solely through exactly that many proxies. Either way the kernel receives one sanitized client address; a malformed value stops the web tier at startup |",
         "| `CAPYBARA_WEB_SHUTDOWN_GRACE_MS` | Production only: after SIGTERM / SIGINT, how long in-flight requests (including SSE streams) may run before the process exits; default 5000 |",
+        "| `CAPYBARA_WEB_KEEP_ALIVE_TIMEOUT_MS` | How long an idle HTTP keep-alive connection to the web tier stays open, in milliseconds; default 65000. Keep it above the idle timeout of any load balancer or proxy in front of the web tier (often 60 s): otherwise the web tier may close a connection just as the proxy reuses it, and that request fails (a 502 at the proxy). A value that is not a positive integer stops the web tier at startup |",
         "| `CAPYBARA_WEB_MAX_BODY_BYTES` | Request body limit of the `/api/*` proxy, default 1 MiB (matches the kernel's bodyLimit) |",
-        "| `CAPYBARA_WEB_MAX_PACKAGE_BYTES` | Request body limit for extension package and plugin uploads (`/api/v1/admin/extensions/packages/file`, `/api/v1/admin/catalog/import/file`), default 50 MiB, forwarded while being read. This is the web tier's limit; the kernel additionally rejects by `packages.maxBytes`. Raise both together, otherwise a large package uploaded through the web is first rejected by the web tier with a 413 |",
+        "| `CAPYBARA_WEB_MAX_PACKAGE_BYTES` | Request body limit for extension package and plugin uploads (`/api/v1/admin/extensions/packages/file`, `/api/v1/admin/catalog/import/file`, `/api/v1/orgs/:orgId/catalog/uploads/file`), default 50 MiB, forwarded while being read. This is the web tier's limit; the kernel additionally rejects by `packages.maxBytes`. Raise both together, otherwise a large package uploaded through the web is first rejected by the web tier with a 413 |",
         "| `CAPYBARA_WEB_OBJECT_STORE_URL` | Object storage on the web origin: the object store's address as web reaches it (e.g. `http://seaweedfs-s3:8333`). When set, web proxies `/<bucket>/**` (and `/<bucket>` itself for POST only) there, so browsers upload attachments (presigned POST) and download attachments and artifacts (presigned GET) through web; set the object-store extension's `publicEndpoint` to the web origin with `forcePathStyle: true`. Only GET, HEAD and POST; the path is forwarded unchanged; cookies and authorization are not forwarded; responses carry `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`; uploads are capped at `CAPYBARA_WEB_MAX_PACKAGE_BYTES`. Unset (default): off |",
         "| `CAPYBARA_WEB_OBJECT_STORE_BUCKET` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the bucket, equal to the object-store extension's `bucket` (it is the first path segment web proxies) |",
         "| `CAPYBARA_WEB_OBJECT_STORE_PUBLIC_HOST` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the host of the extension's `publicEndpoint` (a host such as `capybara.example.com`, or that URL). Sent upstream as `Host` instead of the incoming one, because presigned URLs sign the host they were issued for and front proxies rewrite it |",
+        "| `CAPYBARA_WEB_GATEWAY_URL` | Connected machines on the web origin: a `gateway` replica's address as web reaches it (an http(s) URL, e.g. `http://gateway:8080`). WebSocket upgrades on exactly `/device/connect` are forwarded to it (`capybara-device` connects at `<http.publicUrl>/device/connect`). Unset, they go to `CAPYBARA_KERNEL_URL` (the kernel runs every role unless the deployment splits them), so only deployments with separate gateway replicas set it (compose does). A malformed value stops the web tier at startup |",
         "| `CAPYBARA_DEV_UI` | When set to `1`, production builds also serve the `/dev/ui` component catalog page (off by default) |",
         "",
     ].join("\n");

package/dist/config/load.d.ts

@@ -11,8 +11,9 @@ export declare function resolveConfig(raw: unknown, env: NodeJS.ProcessEnv): Ker
 /** 选来源 → 深合并环境变量覆盖（优先级最高）→ 校验。 */
 export declare function loadConfig(env: NodeJS.ProcessEnv): Promise<KernelConfig>;
 /**
- * 与 {@link loadConfig} 相同，另给出各插件部署配置字段的来源（文件 / Nacos / 环境变量，见
- * {@link extensionConfigSources}）：传给 `createKernel` 的 `extensionConfigSources`，后台据此把这些字段标为只读（D8）。
+ * Like {@link loadConfig}, and also where each extension deployment config field comes from (file
+ * / Nacos / environment, see {@link extensionConfigSources}): the `extensionConfigSources` option of
+ * `startKernelApp` / `createKernelApp`, by which the admin console marks these fields read-only (D8).
  */
 export declare function loadConfigWithSources(env: NodeJS.ProcessEnv): Promise<{
     config: KernelConfig;

package/dist/config/load.js

@@ -85,8 +85,9 @@ export async function loadConfig(env) {
     return resolveConfig(await selectConfigSource(env).load(), env);
 }
 /**
- * 与 {@link loadConfig} 相同，另给出各插件部署配置字段的来源（文件 / Nacos / 环境变量，见
- * {@link extensionConfigSources}）：传给 `createKernel` 的 `extensionConfigSources`，后台据此把这些字段标为只读（D8）。
+ * Like {@link loadConfig}, and also where each extension deployment config field comes from (file
+ * / Nacos / environment, see {@link extensionConfigSources}): the `extensionConfigSources` option of
+ * `startKernelApp` / `createKernelApp`, by which the admin console marks these fields read-only (D8).
  */
 export async function loadConfigWithSources(env) {
     const raw = await selectConfigSource(env).load();

package/dist/config/nacos-source.js

@@ -101,7 +101,14 @@ export function createNacosSource(opts) {
         return doFetch(withToken(fresh), init);
     }
     async function fetchText(signal) {
-        const qs = new URLSearchParams({ dataId: opts.dataId, group, namespaceId: opts.namespace });
+        // `tenant` too: Nacos 2.3 authorizes a namespace-scoped user by `tenant` only, and treats a
+        // request without it as the public namespace (403 for a user granted just this namespace)
+        const qs = new URLSearchParams({
+            dataId: opts.dataId,
+            group,
+            namespaceId: opts.namespace,
+            tenant: opts.namespace,
+        });
         const timeout = AbortSignal.timeout(timeoutMs);
         const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
         let res;
@@ -150,7 +157,9 @@ export function createNacosSource(opts) {
         const body = new URLSearchParams({ "Listening-Configs": `${entry}\u0001` });
         let res;
         try {
-            res = await authedFetch(`${server}/nacos/v1/cs/configs/listener`, {
+            // The namespace in the body is not what Nacos authorizes; `tenant` is (see fetchText)
+            const qs = new URLSearchParams({ tenant: opts.namespace });
+            res = await authedFetch(`${server}/nacos/v1/cs/configs/listener?${qs}`, {
                 method: "POST",
                 headers: {
                     "Long-Pulling-Timeout": String(LONG_POLL_MS),

package/dist/config/schema.d.ts

@@ -51,6 +51,7 @@ export declare const KernelConfigSchema: z.ZodObject<{
         url: z.ZodString;
         poolMax: z.ZodDefault<z.ZodNumber>;
         connectTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        idleTimeoutMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     redis: z.ZodPrefault<z.ZodObject<{
         url: z.ZodString;
@@ -101,6 +102,7 @@ export declare const KernelConfigSchema: z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
         trustProxy: z.ZodDefault<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>, unknown>>;
         replicaId: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        swagger: z.ZodDefault<z.ZodBoolean>;
         publicUrl: z.ZodOptional<z.ZodURL>;
     }, z.core.$strip>>;
     roles: z.ZodDefault<z.ZodPreprocess<z.ZodArray<z.ZodEnum<{
@@ -118,6 +120,7 @@ export declare const KernelConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     runtime: z.ZodDefault<z.ZodObject<{
         maxSteps: z.ZodDefault<z.ZodNumber>;
+        wakeOnBackgroundTask: z.ZodDefault<z.ZodBoolean>;
         maxRunSeconds: z.ZodDefault<z.ZodNumber>;
         streamIdleMs: z.ZodDefault<z.ZodNumber>;
         maxOutputTokens: z.ZodDefault<z.ZodNumber>;
@@ -174,15 +177,32 @@ export declare const KernelConfigSchema: z.ZodObject<{
         requestMediaBytes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     subagents: z.ZodPrefault<z.ZodObject<{
-        maxConcurrentPerRun: z.ZodDefault<z.ZodNumber>;
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        maxConcurrentPerConversation: z.ZodDefault<z.ZodNumber>;
         maxDispatchesPerRun: z.ZodDefault<z.ZodNumber>;
         maxTokensPerRun: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    web: z.ZodPrefault<z.ZodObject<{
+        search: z.ZodPrefault<z.ZodObject<{
+            maxResults: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        fetch: z.ZodPrefault<z.ZodObject<{
+            maxPageChars: z.ZodDefault<z.ZodNumber>;
+            maxAnswerTokens: z.ZodDefault<z.ZodNumber>;
+            cacheSeconds: z.ZodDefault<z.ZodNumber>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     sandbox: z.ZodPrefault<z.ZodObject<{
-        image: z.ZodDefault<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
         lockWaitSeconds: z.ZodDefault<z.ZodNumber>;
         maxConcurrentCommands: z.ZodDefault<z.ZodNumber>;
         deliverMaxBytes: z.ZodDefault<z.ZodNumber>;
+        background: z.ZodPrefault<z.ZodObject<{
+            maxTasks: z.ZodDefault<z.ZodNumber>;
+            maxSeconds: z.ZodDefault<z.ZodNumber>;
+            pollSeconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
         limits: z.ZodPrefault<z.ZodObject<{
             cpu: z.ZodDefault<z.ZodNumber>;
             memoryMb: z.ZodDefault<z.ZodNumber>;
@@ -199,6 +219,16 @@ export declare const KernelConfigSchema: z.ZodObject<{
             allowHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    environments: z.ZodPrefault<z.ZodObject<{
+        maxPersonal: z.ZodDefault<z.ZodNumber>;
+        device: z.ZodPrefault<z.ZodObject<{
+            reconnectGraceSeconds: z.ZodDefault<z.ZodNumber>;
+            leaseTtlMs: z.ZodDefault<z.ZodNumber>;
+            authCodeTtlSeconds: z.ZodDefault<z.ZodNumber>;
+            pollIntervalSeconds: z.ZodDefault<z.ZodNumber>;
+            maxFrameBytes: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     evals: z.ZodPrefault<z.ZodObject<{
         orgConcurrency: z.ZodDefault<z.ZodNumber>;
         workerConcurrency: z.ZodDefault<z.ZodNumber>;
@@ -209,6 +239,10 @@ export declare const KernelConfigSchema: z.ZodObject<{
         judgeMaxOutputTokens: z.ZodDefault<z.ZodNumber>;
         maxConsecutiveErrors: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    models: z.ZodPrefault<z.ZodObject<{
+        listTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        embedTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     hooks: z.ZodPrefault<z.ZodObject<{
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         usageReportConcurrency: z.ZodDefault<z.ZodNumber>;