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

package/dist/tools/resources.d.ts

@@ -1,6 +1,6 @@
 import { type ConnectorSession, type ToolResult, type ToolSpec } from "@capybara-hq/plugin-sdk";
 /**
- * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ * 连接器 resources 的两个内核工具（brief：`mcp__<slug>__list_resources`、`mcp__<slug>__read_resource {uri}`）。
  *
  * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
  * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和

package/dist/tools/resources.js

@@ -1,6 +1,6 @@
 import { ToolError, } from "@capybara-hq/plugin-sdk";
 /**
- * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ * 连接器 resources 的两个内核工具（brief：`mcp__<slug>__list_resources`、`mcp__<slug>__read_resource {uri}`）。
  *
  * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
  * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和

package/dist/tools/specs.d.ts

@@ -1,14 +1,15 @@
 import type { ToolSpec } from "@capybara-hq/plugin-sdk";
-import type { Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 /**
  * 把工具定义按指纹存进 `capybara.tool_specs`（内容寻址：同一指纹只存一次，已存在不改）。
  * `model_call` 只记 `{key, specHash}`，定义本身存这里——连接器刷新 / 插件升级改了定义之后，早先请求用过的定义
  * 仍可按指纹取回，模型请求可由日志还原。
  */
-export declare function recordToolSpecs(db: KernelDb | Transaction<KernelDatabase>, specs: readonly {
+export declare function recordToolSpecs(
+/** The pool or a transaction (a transaction is a Kysely handle too). */
+db: KernelSchemaDb, specs: readonly {
     specHash: string;
     spec: ToolSpec;
 }[]): Promise<void>;
 /** 按指纹取回工具定义；没有记录 → null。 */
-export declare function loadToolSpec(db: KernelDb, specHash: string): Promise<ToolSpec | null>;
+export declare function loadToolSpec(db: KernelSchemaDb, specHash: string): Promise<ToolSpec | null>;

package/dist/tools/specs.js

@@ -3,7 +3,9 @@
  * `model_call` 只记 `{key, specHash}`，定义本身存这里——连接器刷新 / 插件升级改了定义之后，早先请求用过的定义
  * 仍可按指纹取回，模型请求可由日志还原。
  */
-export async function recordToolSpecs(db, specs) {
+export async function recordToolSpecs(
+/** The pool or a transaction (a transaction is a Kysely handle too). */
+db, specs) {
     const unique = new Map();
     for (const s of specs)
         if (!unique.has(s.specHash))

package/dist/tools/tools.module.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tools and connectors: credentials, output archives, the builtin tools and the registry,
+ * approvals and questions (their decisions are the domain events `approval.decided` /
+ * `question.answered`), drift detection (the producer of the one-off `drift-connector` jobs the
+ * maintenance processor consumes), the breaker, connector content, the execution pipeline, org
+ * connectors and the OAuth connect flow. The periodic jobs (`ToolJobs`: the drift scan and the
+ * output cleanup) are the worker role's (`WorkerModule`).
+ */
+export declare class ToolsModule {
+}

package/dist/tools/tools.module.js

@@ -0,0 +1,113 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { BackgroundModule } from "../background/background.module.js";
+import { ConversationAccessModule } from "../conversations/access.js";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
+import { EventLogModule } from "../conversations/event-log.js";
+import { EnvironmentsModule } from "../environments/environments.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { ModelsModule } from "../models/models.module.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { PlatformModule } from "../platform/platform.module.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { StepLogModule } from "../runtime/step-log.js";
+import { SubagentsModule } from "../runtime/subagents/subagents.service.js";
+import { UsageReportModule } from "../runtime/usage-report.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { SkillsModule } from "../skills/skills.module.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { ApprovalsService } from "./approvals.service.js";
+import { Breaker } from "./breaker.js";
+import { BuiltinTools } from "./builtins/builtin-tools.js";
+import { WebPages } from "./builtins/web/page-cache.js";
+import { ConnectorContent } from "./connector-content.js";
+import { ConnectorsService } from "./connectors.service.js";
+import { Credentials } from "./credentials.js";
+import { ToolDrift } from "./drift.js";
+import { ConversationToolInfo, OrgExtensionTools } from "./info.js";
+import { OAuthFlow } from "./oauth/flow.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
+import { ToolOutputs } from "./outputs.js";
+import { ToolPipeline } from "./pipeline.js";
+import { QuestionsService } from "./questions.service.js";
+import { ToolRegistry } from "./registry.js";
+/**
+ * Tools and connectors: credentials, output archives, the builtin tools and the registry,
+ * approvals and questions (their decisions are the domain events `approval.decided` /
+ * `question.answered`), drift detection (the producer of the one-off `drift-connector` jobs the
+ * maintenance processor consumes), the breaker, connector content, the execution pipeline, org
+ * connectors and the OAuth connect flow. The periodic jobs (`ToolJobs`: the drift scan and the
+ * output cleanup) are the worker role's (`WorkerModule`).
+ */
+let ToolsModule = class ToolsModule {
+};
+ToolsModule = __decorate([
+    Module({
+        imports: [
+            EventLogModule,
+            AttachmentsModule,
+            ExtensionsModule,
+            StorageModule,
+            SkillsModule,
+            OrgLockModule,
+            // the `Agent` tool's dispatch
+            SubagentsModule,
+            // the builtin sandbox and skill tools run in the conversation's environment
+            SandboxModule,
+            EnvironmentsModule,
+            // `Bash` with run_in_background records its task; TaskOutput / TaskStop finish and stop it
+            BackgroundModule,
+            // the conversation page's tool metadata reads only what the viewer may see
+            ConversationAccessModule,
+            // the WebFetch extraction call: its purpose, usage report and step writes
+            ModelsModule,
+            UsageReportModule,
+            StepLogModule,
+            // the `Platform` tool's operations, actor facts and agent docs (imports no domain module)
+            PlatformModule,
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
+        providers: [
+            Credentials,
+            ToolOutputs,
+            BuiltinTools,
+            WebPages,
+            ToolRegistry,
+            ApprovalsService,
+            QuestionsService,
+            ToolDrift,
+            Breaker,
+            ConnectorContent,
+            ToolPipeline,
+            ConnectorsService,
+            OAuthFlow,
+            ConversationToolInfo,
+            OrgExtensionTools,
+            OrgToolSwitches,
+        ],
+        exports: [
+            Credentials,
+            ToolOutputs,
+            BuiltinTools,
+            ToolRegistry,
+            ApprovalsService,
+            QuestionsService,
+            ToolDrift,
+            Breaker,
+            ConnectorContent,
+            ToolPipeline,
+            ConnectorsService,
+            OAuthFlow,
+            ConversationToolInfo,
+            OrgExtensionTools,
+            OrgToolSwitches,
+        ],
+    })
+], ToolsModule);
+export { ToolsModule };

package/dist/tools/validate.js

@@ -1,5 +1,5 @@
 import { Ajv2020 } from "ajv/dist/2020.js";
-import { canonicalJson } from "./registry.js";
+import { canonicalJson } from "./canonical-json.js";
 /**
  * 编译结果缓存的上限：超过后整体丢弃（工具定义每步从库里重新读出，缓存不能无限增长）。
  * 缓存的是由定义推导出的只读数据，不是跨进程状态。

package/dist/ui/call-extension.d.ts

@@ -0,0 +1,16 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+/**
+ * Calls an extension with a time limit and an abort signal (plugin views, actions and file
+ * previewers): over the limit the signal aborts and the call is 504 `ui.timeout`; a throw is
+ * `failCode` (502) without echoing the extension's message. An `ApiError` thrown by `fn` passes.
+ */
+export declare function callExtension<T>(o: {
+    log: Pick<Logger, "warn">;
+    plugin: string;
+    what: string;
+    fields: Record<string, unknown>;
+    timeoutMs: number;
+    failCode: "ui.render_failed" | "ui.action_failed";
+    failMessage: string;
+    fn: (signal: AbortSignal) => Promise<T>;
+}): Promise<T>;

package/dist/ui/call-extension.js

@@ -0,0 +1,38 @@
+import { ApiError } from "../errors.js";
+/**
+ * Calls an extension with a time limit and an abort signal (plugin views, actions and file
+ * previewers): over the limit the signal aborts and the call is 504 `ui.timeout`; a throw is
+ * `failCode` (502) without echoing the extension's message. An `ApiError` thrown by `fn` passes.
+ */
+export async function callExtension(o) {
+    const ac = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ac.abort(new Error(`plugin ui ${o.what} timed out`));
+            resolve("timeout");
+        }, o.timeoutMs);
+    });
+    try {
+        const r = await Promise.race([
+            Promise.resolve()
+                .then(() => o.fn(ac.signal))
+                .then((value) => ({ value })),
+            timeout,
+        ]);
+        if (r === "timeout") {
+            o.log.warn(`plugin ui ${o.what} timed out`, { ...o.fields, timeoutMs: o.timeoutMs });
+            throw new ApiError("ui.timeout", `Plugin ${o.plugin} did not respond within ${o.timeoutMs / 1000}s`);
+        }
+        return r.value;
+    }
+    catch (e) {
+        if (e instanceof ApiError)
+            throw e;
+        o.log.warn(`plugin ui ${o.what} failed`, { ...o.fields, err: e });
+        throw new ApiError(o.failCode, o.failMessage);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/ui/embed-token.d.ts

@@ -6,20 +6,21 @@ export declare const EMBED_TOKEN_TTL_SECONDS = 300;
 export declare const EMBED_TOKEN_SKEW_SECONDS = 30;
 /** HKDF 用途（keyring 派生时 info 为 `capybara:capybara-embed/1`），也是签名输入的域前缀。 */
 export declare const EMBED_KEY_INFO = "capybara-embed/1";
+/** Optional provider: the clock {@link EmbedTokens} issues and checks with (default `Date.now`; tests). */
+export declare const EMBED_TOKEN_CLOCK: unique symbol;
 /**
  * 嵌入令牌：`base64url(JSON 声明).base64url(HMAC-SHA256(key, "capybara-embed/1." + 第一段))`。
  * - 格式固定、没有头（没有 alg 可混淆）；密钥由主密钥环经 HKDF 派生，轮换后上一把主密钥签的令牌仍可校验到过期；
  * - 校验：严格 base64url、常量时间比较签名、逐字段核对声明、`exp` 容许 {@link EMBED_TOKEN_SKEW_SECONDS} 秒偏差、
  *   `exp` 不得超过「现在 + 有效期 + 偏差」、`plugin` 必须是调用方插件；任何一项不过都返回 null（不说明原因）。
- * 无状态（不落库、不进 Redis）：各副本用同一主密钥即可校验，不需要共享状态。
+ * 无状态（不落库、不进 Redis）：各副本用同一主密钥即可校验，不需要共享状态。One provider: the UI
+ * routes issue tokens with it and every extension's `ctx` verifies them with it.
  */
 export declare class EmbedTokens {
+    private readonly now;
     private readonly current;
     private readonly keys;
-    private readonly now;
-    constructor(keyring: Keyring, opts?: {
-        now?: () => number;
-    });
+    constructor(keyring: Keyring, now?: () => number);
     /** 签发：`exp` = 现在 + {@link EMBED_TOKEN_TTL_SECONDS}。 */
     issue(c: Omit<EmbedClaims, "exp">): {
         token: string;
@@ -29,3 +30,6 @@ export declare class EmbedTokens {
     /** 校验令牌并要求它签给 `plugin`；不通过返回 null。 */
     verify(token: unknown, plugin: string): EmbedClaims | null;
 }
+/** {@link EmbedTokens} on its own: the extension host (`ctx`) and the UI routes import it. */
+export declare class EmbedTokensModule {
+}

package/dist/ui/embed-token.js

@@ -1,4 +1,15 @@
+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 { createHmac, timingSafeEqual } from "node:crypto";
+import { Inject, Injectable, Module, Optional } from "@nestjs/common";
+import { KEYRING } from "../infra/tokens.js";
 import { ORG_ROLES } from "../orgs/roles.js";
 /** 嵌入令牌的有效期（秒）。网页在过期前 60 秒续期。 */
 export const EMBED_TOKEN_TTL_SECONDS = 300;
@@ -63,23 +74,26 @@ function parseClaims(v) {
         exp: c.exp,
     };
 }
+/** Optional provider: the clock {@link EmbedTokens} issues and checks with (default `Date.now`; tests). */
+export const EMBED_TOKEN_CLOCK = Symbol("EMBED_TOKEN_CLOCK");
 /**
  * 嵌入令牌：`base64url(JSON 声明).base64url(HMAC-SHA256(key, "capybara-embed/1." + 第一段))`。
  * - 格式固定、没有头（没有 alg 可混淆）；密钥由主密钥环经 HKDF 派生，轮换后上一把主密钥签的令牌仍可校验到过期；
  * - 校验：严格 base64url、常量时间比较签名、逐字段核对声明、`exp` 容许 {@link EMBED_TOKEN_SKEW_SECONDS} 秒偏差、
  *   `exp` 不得超过「现在 + 有效期 + 偏差」、`plugin` 必须是调用方插件；任何一项不过都返回 null（不说明原因）。
- * 无状态（不落库、不进 Redis）：各副本用同一主密钥即可校验，不需要共享状态。
+ * 无状态（不落库、不进 Redis）：各副本用同一主密钥即可校验，不需要共享状态。One provider: the UI
+ * routes issue tokens with it and every extension's `ctx` verifies them with it.
  */
-export class EmbedTokens {
+let EmbedTokens = class EmbedTokens {
+    now;
     current;
     keys;
-    now;
-    constructor(keyring, opts = {}) {
+    constructor(keyring, now = Date.now) {
+        this.now = now;
         const derived = keyring.deriveKey(EMBED_KEY_INFO);
         const ids = [derived.currentId, ...keyring.toJSON().previousIds];
         this.current = derived.current;
         this.keys = ids.map((id) => derived.byId(id)).filter((k) => k !== undefined);
-        this.now = opts.now ?? Date.now;
     }
     /** 签发：`exp` = 现在 + {@link EMBED_TOKEN_TTL_SECONDS}。 */
     issue(c) {
@@ -126,7 +140,21 @@ export class EmbedTokens {
             return null;
         return claims;
     }
-}
+};
+EmbedTokens = __decorate([
+    Injectable(),
+    __param(0, Inject(KEYRING)),
+    __param(1, Optional()),
+    __param(1, Inject(EMBED_TOKEN_CLOCK))
+], EmbedTokens);
+export { EmbedTokens };
 function mac(key, payload) {
     return createHmac("sha256", key).update(`${EMBED_KEY_INFO}.${payload}`).digest();
 }
+/** {@link EmbedTokens} on its own: the extension host (`ctx`) and the UI routes import it. */
+let EmbedTokensModule = class EmbedTokensModule {
+};
+EmbedTokensModule = __decorate([
+    Module({ providers: [EmbedTokens], exports: [EmbedTokens] })
+], EmbedTokensModule);
+export { EmbedTokensModule };

package/dist/ui/ui-stream.d.ts

@@ -1,37 +1,42 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
 import type { CredentialCheck } from "../identity/credential-check.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
 import { type OrgRole } from "../orgs/roles.js";
-import type { SseOutput, StreamBus, StreamHandle } from "../runtime/stream.js";
-export interface OrgUiStreamsDeps {
-    bus: StreamBus;
-    /**
-     * 调用者此刻的组织角色（组织未删除、账号 active、仍有成员关系，否则 undefined）：
-     * 连接建立时与每 `sseRecheckMs` 复核一次；组织级刷新只服务组织页面，要 member 以上（A38）。
-     */
-    memberRole(orgId: string, accountId: string): Promise<OrgRole | undefined>;
-    config: () => KernelConfig;
-    log: Pick<Logger, "warn">;
-}
+import { type SseOutput, type StreamBus, type StreamHandle } from "../runtime/stream.js";
 export interface OrgUiStreamParams {
     orgId: string;
     viewerAccountId: string;
     credential: CredentialCheck;
 }
-/** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
-export declare function orgMembership(db: KernelDb): OrgUiStreamsDeps["memberRole"];
+/** The org role the org UI stream re-checks. */
+export declare class UiStreamMembership {
+    private readonly db;
+    constructor(db: KernelDb);
+    /** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
+    role(orgId: string, accountId: string): Promise<OrgRole | undefined>;
+}
 /**
  * 组织级界面刷新流（SSE）：订阅内核主题 `org-ui.<orgId>`，把插件 `ctx.ui.invalidate`（不带对话）的刷新
  * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
  * （订阅、心跳与复核定时器），停机时一并关闭。
  */
 export declare class OrgUiStreams {
-    private readonly d;
     private readonly active;
-    constructor(d: OrgUiStreamsDeps);
+    /** Set by {@link closeAll}: streams opened afterwards end as soon as they begin. */
+    private closing;
+    private readonly d;
+    /**
+     * Closes the streams when the shutdown begins (readiness answers 503 from that moment) and
+     * latches: streams opened afterwards end at once, so the HTTP phase of the stop never waits on
+     * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
+     * streams end with their connections.
+     */
+    constructor(bus: StreamBus, membership: Pick<UiStreamMembership, "role">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn">, shutdown?: Pick<GracefulShutdown, "signal">);
     /** 复核凭据与成员关系并订阅；失败时尚未写响应，调用方按普通错误返回。 */
     open(p: OrgUiStreamParams, out: SseOutput): Promise<StreamHandle>;
+    /** Closes every stream of this process (at shutdown) and latches, like `ConversationStreams`. */
     closeAll(): void;
     get size(): number;
 }

package/dist/ui/ui-stream.js

@@ -1,10 +1,30 @@
+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 } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { roleAtLeast } from "../orgs/roles.js";
+import { endedStream, } from "../runtime/stream.js";
 import { isUiBusMessage, orgUiTopic, PAGE_MIN_ROLE, uiFrame } from "./registry.js";
-/** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
-export function orgMembership(db) {
-    return async (orgId, accountId) => {
-        const row = await db
+/** The org role the org UI stream re-checks. */
+let UiStreamMembership = class UiStreamMembership {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
+    async role(orgId, accountId) {
+        const row = await this.db
             .selectFrom("memberships")
             .innerJoin("orgs", "orgs.id", "memberships.org_id")
             .innerJoin("accounts", "accounts.id", "memberships.account_id")
@@ -15,8 +35,13 @@ export function orgMembership(db) {
             .where("accounts.status", "=", "active")
             .executeTakeFirst();
         return row?.role;
-    };
-}
+    }
+};
+UiStreamMembership = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], UiStreamMembership);
+export { UiStreamMembership };
 async function authorize(d, p) {
     const denied = await p.credential();
     if (denied !== null)
@@ -33,17 +58,36 @@ const MAX_BACKLOG_BYTES = 1024 * 1024;
  * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
  * （订阅、心跳与复核定时器），停机时一并关闭。
  */
-export class OrgUiStreams {
-    d;
+let OrgUiStreams = class OrgUiStreams {
     active = new Set();
-    constructor(d) {
-        this.d = d;
+    /** Set by {@link closeAll}: streams opened afterwards end as soon as they begin. */
+    closing = false;
+    d;
+    /**
+     * Closes the streams when the shutdown begins (readiness answers 503 from that moment) and
+     * latches: streams opened afterwards end at once, so the HTTP phase of the stop never waits on
+     * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
+     * streams end with their connections.
+     */
+    constructor(bus, membership, config, log, shutdown) {
+        this.d = {
+            bus,
+            memberRole: (orgId, accountId) => membership.role(orgId, accountId),
+            config,
+            log,
+        };
+        if (shutdown?.signal.aborted)
+            this.closeAll();
+        else
+            shutdown?.signal.addEventListener("abort", () => this.closeAll(), { once: true });
     }
     /** 复核凭据与成员关系并订阅；失败时尚未写响应，调用方按普通错误返回。 */
     async open(p, out) {
         const denied = await authorize(this.d, p);
         if (denied !== null)
             throw new ApiError(denied, "Access denied");
+        if (this.closing)
+            return endedStream(out);
         const conn = new OrgUiConnection(this.d, p, out, () => this.active.delete(conn));
         this.active.add(conn);
         try {
@@ -53,16 +97,32 @@ export class OrgUiStreams {
             conn.close();
             throw e;
         }
+        if (this.closing) {
+            conn.close();
+            return endedStream(out);
+        }
         return conn;
     }
+    /** Closes every stream of this process (at shutdown) and latches, like `ConversationStreams`. */
     closeAll() {
+        this.closing = true;
         for (const c of [...this.active])
             c.close();
     }
     get size() {
         return this.active.size;
     }
-}
+};
+OrgUiStreams = __decorate([
+    Injectable(),
+    __param(0, Inject(KERNEL_BUS)),
+    __param(1, Inject(UiStreamMembership)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Optional()),
+    __param(4, Inject(GracefulShutdown))
+], OrgUiStreams);
+export { OrgUiStreams };
 class OrgUiConnection {
     d;
     p;
@@ -94,7 +154,7 @@ class OrgUiConnection {
         if (this.closed)
             return;
         this.begun = true;
-        const { sseHeartbeatMs, sseRecheckMs } = this.d.config().runtime;
+        const { sseHeartbeatMs, sseRecheckMs } = this.d.config.get().runtime;
         this.timers.push(setInterval(() => this.write(": ping\n\n"), sseHeartbeatMs), setInterval(() => void this.recheck(), sseRecheckMs));
     }
     close(mode = "end") {

package/dist/ui/ui.module.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extension UI on the kernel side: the views and actions (`ctx.ui`), the embed tokens
+ * ({@link EmbedTokensModule}, re-exported; the extension host verifies them with the same
+ * provider) and the org UI refresh stream.
+ */
+export declare class UiModule {
+}

package/dist/ui/ui.module.js

@@ -0,0 +1,28 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { ConversationsModule } from "../conversations/conversations.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { FilesModule } from "../files/files.module.js";
+import { EmbedTokensModule } from "./embed-token.js";
+import { OrgUiStreams, UiStreamMembership } from "./ui-stream.js";
+import { UiViews } from "./views.js";
+/**
+ * Extension UI on the kernel side: the views and actions (`ctx.ui`), the embed tokens
+ * ({@link EmbedTokensModule}, re-exported; the extension host verifies them with the same
+ * provider) and the org UI refresh stream.
+ */
+let UiModule = class UiModule {
+};
+UiModule = __decorate([
+    Module({
+        imports: [ExtensionsModule, ConversationsModule, FilesModule, EmbedTokensModule],
+        providers: [UiViews, UiStreamMembership, OrgUiStreams],
+        exports: [UiViews, OrgUiStreams, EmbedTokensModule],
+    })
+], UiModule);
+export { UiModule };

package/dist/ui/views.controller.d.ts

@@ -1,14 +1,18 @@
 import { type UiActionResult, type UiView } from "@capybara-hq/plugin-sdk";
-import { type OnModuleDestroy } from "@nestjs/common";
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
-import type { ApiTokenService } from "../identity/api-tokens.js";
+import { ApiTokenService } from "../identity/api-tokens.js";
 import { type Principal } from "../identity/principal.js";
-import type { SessionService } from "../identity/sessions.js";
+import { SessionService } from "../identity/sessions.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import { type EmbedTokens } from "./embed-token.js";
-import type { OrgUiStreams } from "./ui-stream.js";
-import type { UiContributionItem, UiViews } from "./views.js";
+import { EmbedTokens } from "./embed-token.js";
+import { OrgUiStreams } from "./ui-stream.js";
+import { type UiContributionItem, UiViews } from "./views.js";
+/** The contribution named in a view / action / embed path (`:plugin/:id`). */
+declare const ContributionParams: z.ZodObject<{
+    plugin: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
 declare const ViewQuery: z.ZodObject<{
     conversationId: z.ZodOptional<z.ZodString>;
     locale: z.ZodDefault<z.ZodEnum<{
@@ -53,7 +57,7 @@ declare const EmbedTokenBody: z.ZodDefault<z.ZodObject<{
  * 角色（A38）：组织页面（`place: "page"`，含组织级刷新流）只给 member 以上，guest 一律 404 `ui.not_found`、
  * 列表里也不出现；对话位置的贡献给能访问该对话的任何成员。插件收到的 `role` 来自 OrgGuard 查出的成员关系。
  */
-export declare class UiController implements OnModuleDestroy {
+export declare class UiController {
     private readonly views;
     private readonly streams;
     private readonly sessions;
@@ -63,11 +67,11 @@ export declare class UiController implements OnModuleDestroy {
     contributions(principal: Principal, org: OrgContext): Promise<{
         items: UiContributionItem[];
     }>;
-    view(principal: Principal, org: OrgContext, plugin: string, id: string, q: z.infer<typeof ViewQuery>): Promise<{
+    view(principal: Principal, org: OrgContext, { plugin, id }: z.infer<typeof ContributionParams>, q: z.infer<typeof ViewQuery>): Promise<{
         view: UiView;
     }>;
-    action(principal: Principal, org: OrgContext, plugin: string, id: string, body: z.infer<typeof ActionBody>): Promise<UiActionResult>;
-    embedToken(principal: Principal, org: OrgContext, plugin: string, id: string, body: z.infer<typeof EmbedTokenBody>): Promise<{
+    action(principal: Principal, org: OrgContext, { plugin, id }: z.infer<typeof ContributionParams>, body: z.infer<typeof ActionBody>): Promise<UiActionResult>;
+    embedToken(principal: Principal, org: OrgContext, { plugin, id }: z.infer<typeof ContributionParams>, body: z.infer<typeof EmbedTokenBody>): Promise<{
         token: string;
         src: string;
         expiresAt: string;
@@ -75,7 +79,5 @@ export declare class UiController implements OnModuleDestroy {
     }>;
     /** 组织级刷新流：与会话流一样用 `reply.hijack()` 直接写原始响应；心跳与复核间隔同 `runtime.sse*`。 */
     stream(principal: Principal, org: OrgContext, req: FastifyRequest, reply: FastifyReply): Promise<void>;
-    /** 停机：关闭本进程的全部组织刷新流。 */
-    onModuleDestroy(): void;
 }
 export {};