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

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,11 @@ 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>;

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 就是它，于是落到同一个对话。

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/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

@@ -101,6 +101,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<{

package/dist/config/schema.js

@@ -207,9 +207,9 @@ export const KernelConfigSchema = z.object({
         dir: z
             .string()
             .min(1)
-            .default("/var/lib/capybara/plugins")
+            .default(".capybara/plugins")
             .meta(meta({
-            description: "Local directory where each replica unpacks installed extension packages (<dir>/<name>/<first 16 hex of sha256>/); safe to wipe, replicas re-download from the package store",
+            description: "Local directory where each replica unpacks installed extension packages (<dir>/<name>/<first 16 hex of sha256>/), relative to the working directory unless absolute (the image sets /var/lib/capybara/plugins); safe to wipe, replicas re-download from the package store",
         })),
         drainSeconds: z
             .number()
@@ -336,7 +336,7 @@ export const KernelConfigSchema = z.object({
             .min(1)
             .default(360)
             .meta(meta({
-            description: "Minutes between periodic refreshes of every enabled marketplace (one maintenance job for all replicas)",
+            description: "Minutes between periodic refreshes of every enabled marketplace (one run per period across all replicas)",
         })),
         maxIndexBytes: z
             .number()
@@ -472,6 +472,12 @@ export const KernelConfigSchema = z.object({
             .meta(meta({
             description: "Optional replica identifier; when set, every HTTP response carries an x-capybara-replica header with this value (used by the dual-replica test harness and for debugging load balancers)",
         })),
+        swagger: z
+            .boolean()
+            .default(false)
+            .meta(meta({
+            description: "Serve the OpenAPI document and swagger UI at /docs (JSON at /docs-json). The routes are not authenticated, so enable it in development and trials only",
+        })),
         publicUrl: z
             .url()
             .optional()
@@ -479,7 +485,7 @@ export const KernelConfigSchema = z.object({
             description: "Externally reachable origin of the web app (apps/web, which proxies /api to the kernel), not the kernel's own address; required for OAuth connectors: the redirect URI is <publicUrl>/api/v1/oauth/callback (served through the web /api proxy, which also carries the OAuth binding cookie) and the callback redirects to web pages under it, e.g. https://capybara.example.com",
         })),
     })
-        .default({ port: 8080, trustProxy: false }),
+        .default({ port: 8080, trustProxy: false, swagger: false }),
     roles: z
         .preprocess(
     // Also accept a comma-separated string (CAPYBARA_ROLES=api,worker; env values that are not

package/dist/conversations/access.d.ts

@@ -0,0 +1,29 @@
+import { type ExpressionBuilder } from "kysely";
+import type { KernelDatabase } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * A sub-agent's conversation is reached through its parent (sub-agents spec §6.1, review m6, the
+ * same rule as its trajectory): the parent is a chat conversation of the same owner whose agent is
+ * not deleted and still visible to the viewer. Any other kind passes. The child's own `agent_id`
+ * (the dispatched agent for an org agent, §5.5) is checked on top by the callers.
+ */
+export declare const parentReachable: (viewerAccountId: string) => (eb: ExpressionBuilder<KernelDatabase, "conversations">) => import("kysely").ExpressionWrapper<KernelDatabase, "conversations", import("kysely").SqlBool>;
+/**
+ * Whether a person may still see a conversation (one query, no agent view): what the event stream,
+ * attachment downloads, file and output reads and the extension UI check. `ConversationsService`
+ * delegates to it; it depends on the database only, so the attachments (which the skills and tools
+ * use) can check access without the conversations module.
+ */
+export declare class ConversationAccess {
+    private readonly db;
+    constructor(db: KernelDb);
+    /**
+     * 轻量的可见性判定（一条查询，不加载 agent 视图），供长连接（SSE）建立时与定期复核用：
+     * 会话属于该组织且归 viewer 所有、viewer 账号仍为 active、agent 未删除且对 viewer 仍可见
+     * （`visibleTo` 已含「组织未删除、viewer 仍是成员」）。
+     */
+    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
+}
+/** The one {@link ConversationAccess} (database only). */
+export declare class ConversationAccessModule {
+}

package/dist/conversations/access.js

@@ -0,0 +1,86 @@
+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, Module } from "@nestjs/common";
+import { sql } from "kysely";
+import { visibleTo } from "../agents/agent-lookup.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * A sub-agent's conversation is reached through its parent (sub-agents spec §6.1, review m6, the
+ * same rule as its trajectory): the parent is a chat conversation of the same owner whose agent is
+ * not deleted and still visible to the viewer. Any other kind passes. The child's own `agent_id`
+ * (the dispatched agent for an org agent, §5.5) is checked on top by the callers.
+ */
+export const parentReachable = (viewerAccountId) => (eb) => eb.or([
+    eb("conversations.kind", "<>", "subagent"),
+    eb.exists(eb
+        .selectFrom("conversations as p")
+        .innerJoin("agents", "agents.id", "p.agent_id")
+        .select(sql `1`.as("one"))
+        .whereRef("p.id", "=", "conversations.parent_conversation_id")
+        .whereRef("p.org_id", "=", "conversations.org_id")
+        .where("p.account_id", "=", viewerAccountId)
+        .where("p.kind", "=", "chat")
+        .where("agents.deleted_at", "is", null)
+        .where(visibleTo(viewerAccountId))),
+]);
+/**
+ * Whether a person may still see a conversation (one query, no agent view): what the event stream,
+ * attachment downloads, file and output reads and the extension UI check. `ConversationsService`
+ * delegates to it; it depends on the database only, so the attachments (which the skills and tools
+ * use) can check access without the conversations module.
+ */
+let ConversationAccess = class ConversationAccess {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 轻量的可见性判定（一条查询，不加载 agent 视图），供长连接（SSE）建立时与定期复核用：
+     * 会话属于该组织且归 viewer 所有、viewer 账号仍为 active、agent 未删除且对 viewer 仍可见
+     * （`visibleTo` 已含「组织未删除、viewer 仍是成员」）。
+     */
+    async isAccessible(orgId, conversationId, viewerAccountId) {
+        const row = await this.db
+            .selectFrom("conversations")
+            .select("conversations.id")
+            .where("conversations.id", "=", conversationId)
+            .where("conversations.org_id", "=", orgId)
+            .where("conversations.account_id", "=", viewerAccountId)
+            .where("conversations.kind", "in", ["chat", "subagent"])
+            .where(parentReachable(viewerAccountId))
+            .where((eb) => eb.and([
+            eb.exists(eb
+                .selectFrom("accounts")
+                .select(sql `1`.as("one"))
+                .where("accounts.id", "=", viewerAccountId)
+                .where("accounts.status", "=", "active")),
+            eb.exists(eb
+                .selectFrom("agents")
+                .select(sql `1`.as("one"))
+                .whereRef("agents.id", "=", "conversations.agent_id")
+                .where("agents.deleted_at", "is", null)
+                .where(visibleTo(viewerAccountId))),
+        ]))
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+};
+ConversationAccess = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], ConversationAccess);
+export { ConversationAccess };
+/** The one {@link ConversationAccess} (database only). */
+let ConversationAccessModule = class ConversationAccessModule {
+};
+ConversationAccessModule = __decorate([
+    Module({ providers: [ConversationAccess], exports: [ConversationAccess] })
+], ConversationAccessModule);
+export { ConversationAccessModule };