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

package/dist/tools/registry.js

@@ -1,11 +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;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { createHash } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { ExtensionHost } from "../extensions/host.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
 import { estimateTokens } from "../runtime/context/tokens.js";
 import { SUBAGENT_LIMIT_DEFAULTS, subagentLimits } from "../runtime/subagents/limits.js";
 import { resolveRoster } from "../runtime/subagents/roster.js";
 import { AGENT_TOOL, agentToolSpec } from "./builtins/agent.js";
+import { BuiltinTools } from "./builtins/builtin-tools.js";
 import { SANDBOX_TOOL_NAMES } from "./builtins/sandbox/names.js";
+import { canonicalJson } from "./canonical-json.js";
 import { toolKey, toolKeyIssue } from "./naming.js";
+export { canonicalJson } from "./canonical-json.js";
 /**
  * 内核内置工具的名字（Task 10 / Task 19 实现；M5 T8 加沙箱工具）。保存 agent 时内置工具引用按这份清单校验，
  * 不依赖当前是否已注册，避免实现落地顺序影响已保存的定义；运行时未注册的照常报不可用。
@@ -21,18 +38,6 @@ export const BUILTIN_TOOL_NAMES = [
     // phase C: dispatches sub-agents; its description is built per agent from the roster
     "agent",
 ];
-/** 键排序、去掉 undefined 的 JSON（jsonb 不保留键顺序，指纹必须与顺序无关）。 */
-export function canonicalJson(v) {
-    if (Array.isArray(v))
-        return `[${v.map(canonicalJson).join(",")}]`;
-    if (v !== null && typeof v === "object") {
-        const entries = Object.entries(v)
-            .filter(([, x]) => x !== undefined)
-            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-        return `{${entries.map(([k, x]) => `${JSON.stringify(k)}:${canonicalJson(x)}`).join(",")}}`;
-    }
-    return JSON.stringify(v);
-}
 /** The first 16 hex digits of sha256(canonicalJson(v)): a fingerprint independent of key order. */
 export function contentHash(v) {
     return createHash("sha256").update(canonicalJson(v)).digest("hex").slice(0, 16);
@@ -97,14 +102,35 @@ const sourceId = (s) => s.kind === "builtin"
  * Only the first of a key is kept; the same source referenced twice is deduplicated silently,
  * different sources with the same key report a duplicate.
  */
-export class ToolRegistry {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
+let ToolRegistry = class ToolRegistry {
+    db;
+    host;
+    extensions;
+    builtinTools;
+    config;
+    constructor(db, 
+    /** Extension tools and the organization's enabled extensions. */
+    host, 
+    /** The installed connectors (`connector@1`, from the extension registry). */
+    extensions, builtinTools, 
+    /**
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `tool_search` is never
+     * offered and the sub-agent limits are the schema defaults.
+     */
+    config) {
+        this.db = db;
+        this.host = host;
+        this.extensions = extensions;
+        this.builtinTools = builtinTools;
+        this.config = config;
+    }
+    /** The kernel's builtin tools (`tool_search` is added by {@link forAgent}, not by definitions). */
+    get builtins() {
+        return this.builtinTools.list();
     }
     /** `host.list("connector")` 中 `kind` 匹配的第一个实现；未安装返回 undefined。 */
     findConnector(kind) {
-        for (const e of this.deps.host.list("connector")) {
+        for (const e of this.extensions.list("connector")) {
             const impl = e.impl;
             if (impl?.kind === kind)
                 return impl;
@@ -127,10 +153,10 @@ export class ToolRegistry {
      */
     handler(source) {
         if (source.kind === "builtin") {
-            return this.deps.builtins.find((b) => b.spec.name === source.name)?.run;
+            return this.builtins.find((b) => b.spec.name === source.name)?.run;
         }
         if (source.kind === "plugin") {
-            const t = this.deps.host
+            const t = this.host
                 .tools()
                 .find((x) => x.plugin === source.plugin && x.spec.name === source.name);
             if (!t)
@@ -141,15 +167,15 @@ export class ToolRegistry {
     }
     /** The registered builtin tools' specs (display metadata for `tools/info.ts`). */
     builtinSpecs() {
-        return this.deps.builtins.map((b) => b.spec);
+        return this.builtins.map((b) => b.spec);
     }
     /** The loaded extensions' registered tool specs, with their extension's name. */
     extensionToolSpecs() {
-        return this.deps.host.tools().map((t) => ({ plugin: t.plugin, spec: t.spec }));
+        return this.host.tools().map((t) => ({ plugin: t.plugin, spec: t.spec }));
     }
     /** 已安装连接器的 kind 列表（去重，按加载顺序）。 */
     connectorKinds() {
-        return [...new Set(this.deps.host.list("connector").map((e) => e.impl.kind))];
+        return [...new Set(this.extensions.list("connector").map((e) => e.impl.kind))];
     }
     /**
      * 保存 agent 时校验工具引用（只看「存在」，停用 / 待复核 / 插件未启用等运行时状态不拒绝，由 `forAgent` 报不可用）：
@@ -162,7 +188,7 @@ export class ToolRegistry {
     async checkRefs(orgId, refs) {
         const issues = [];
         const owner = new Map();
-        const pluginTools = this.deps.host.tools();
+        const pluginTools = this.host.tools();
         const connectorIds = [
             ...new Set(refs.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : []))),
         ];
@@ -227,7 +253,7 @@ export class ToolRegistry {
      */
     async forAgent(orgId, def) {
         const { tools, unavailable, hidden } = await this.resolve(orgId, def);
-        const sl = def.skillLoad === true && this.deps.builtins.find((x) => x.spec.name === SKILL_LOAD);
+        const sl = def.skillLoad === true && this.builtins.find((x) => x.spec.name === SKILL_LOAD);
         if (sl) {
             tools.push({
                 key: SKILL_LOAD,
@@ -240,7 +266,7 @@ export class ToolRegistry {
         }
         const toolSearch = await this.searchActive(orgId, tools);
         if (toolSearch) {
-            const b = this.deps.builtins.find((x) => x.spec.name === TOOL_SEARCH);
+            const b = this.builtins.find((x) => x.spec.name === TOOL_SEARCH);
             tools.push({
                 key: TOOL_SEARCH,
                 source: { kind: "builtin", name: TOOL_SEARCH },
@@ -253,14 +279,14 @@ export class ToolRegistry {
     }
     /** 是否启用 `tool_search`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
     async searchActive(orgId, tools) {
-        const cfg = this.deps.config?.().tools;
-        if (!cfg || !this.deps.builtins.some((b) => b.spec.name === TOOL_SEARCH))
+        const cfg = this.config?.get().tools;
+        if (!cfg || !this.builtins.some((b) => b.spec.name === TOOL_SEARCH))
             return false;
         const over = tools.length > cfg.searchThresholdTools ||
             estimateToolTokens(tools) > cfg.searchThresholdTokens;
         if (!over)
             return false;
-        return (await readOrgSettings(this.deps.db, orgId)).toolSearch === "on";
+        return (await readOrgSettings(this.db.db, orgId)).toolSearch === "on";
     }
     async resolve(orgId, def) {
         const tools = [];
@@ -288,12 +314,12 @@ export class ToolRegistry {
             ...new Set(def.tools.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : []))),
         ];
         const apps = await this.loadConnectors(orgId, connectorIds);
-        const pluginTools = this.deps.host.tools();
+        const pluginTools = this.host.tools();
         for (const ref of def.tools) {
             if (ref.kind === "builtin") {
                 if (ref.name === TOOL_SEARCH || ref.name === SKILL_LOAD)
                     continue;
-                const b = this.deps.builtins.find((x) => x.spec.name === ref.name);
+                const b = this.builtins.find((x) => x.spec.name === ref.name);
                 if (!b) {
                     unavailable.push({ ref: ref.name, reason: "Built-in tool does not exist" });
                     continue;
@@ -307,7 +333,7 @@ export class ToolRegistry {
                 // empty roster there is nothing to dispatch, so the tool is not offered at all
                 let spec = b.spec;
                 if (b.spec.name === AGENT_TOOL) {
-                    const roster = await resolveRoster(this.deps.db, orgId, { subagents: def.subagents });
+                    const roster = await resolveRoster(this.db.db, orgId, { subagents: def.subagents });
                     if (roster.length === 0)
                         continue;
                     spec = agentToolSpec(roster, await this.maxConcurrentSubagents(orgId));
@@ -420,19 +446,20 @@ export class ToolRegistry {
      * schema default.
      */
     async maxConcurrentSubagents(orgId) {
-        const config = this.deps.config ?? (() => ({ subagents: SUBAGENT_LIMIT_DEFAULTS }));
-        return (await subagentLimits(this.deps.db, config, orgId)).maxConcurrentPerRun;
+        const cfg = this.config;
+        const config = cfg ?? { get: () => ({ subagents: SUBAGENT_LIMIT_DEFAULTS }) };
+        return (await subagentLimits(this.db.db, config, orgId)).maxConcurrentPerRun;
     }
     /** Plugins the organization enabled (built-in plugins always count as enabled, C14). */
     async enabledPlugins(orgId) {
-        return this.deps.host.enabledPlugins(orgId);
+        return this.host.enabledPlugins(orgId);
     }
     async loadConnectors(orgId, ids) {
         const out = new Map();
         if (ids.length === 0)
             return out;
         // 软删除的连接器也读出来，只为给出「已删除」这个更准确的原因（slug 可能已被新连接器复用，按 id 区分）
-        const apps = await this.deps.db
+        const apps = await this.db
             .selectFrom("connectors")
             .select(["id", "slug", "connector", "status", "deleted_at"])
             .where("org_id", "=", orgId)
@@ -441,7 +468,7 @@ export class ToolRegistry {
         const live = apps.filter((a) => a.deleted_at === null).map((a) => a.id);
         const toolRows = live.length === 0
             ? []
-            : await this.deps.db
+            : await this.db
                 .selectFrom("connector_tools")
                 .select([
                 "connector_id",
@@ -478,4 +505,13 @@ export class ToolRegistry {
         }
         return out;
     }
-}
+};
+ToolRegistry = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ExtensionHost)),
+    __param(2, Inject(ExtensionRegistry)),
+    __param(3, Inject(BuiltinTools)),
+    __param(4, Inject(KernelConfigService))
+], ToolRegistry);
+export { ToolRegistry };

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,91 @@
+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 { ConversationAccessModule } from "../conversations/access.js";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
+import { EventLogModule } from "../conversations/event-log.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { SubagentsModule } from "../runtime/subagents/subagents.service.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 { ConnectorContent } from "./connector-content.js";
+import { ConnectorsService } from "./connectors.service.js";
+import { Credentials } from "./credentials.js";
+import { ToolDrift } from "./drift.js";
+import { ConversationToolInfo } from "./info.js";
+import { OAuthFlow } from "./oauth/flow.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 sandbox
+            SandboxModule,
+            // the conversation page's tool metadata reads only what the viewer may see
+            ConversationAccessModule,
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
+        providers: [
+            Credentials,
+            ToolOutputs,
+            BuiltinTools,
+            ToolRegistry,
+            ApprovalsService,
+            QuestionsService,
+            ToolDrift,
+            Breaker,
+            ConnectorContent,
+            ToolPipeline,
+            ConnectorsService,
+            OAuthFlow,
+            ConversationToolInfo,
+        ],
+        exports: [
+            Credentials,
+            ToolOutputs,
+            BuiltinTools,
+            ToolRegistry,
+            ApprovalsService,
+            QuestionsService,
+            ToolDrift,
+            Breaker,
+            ConnectorContent,
+            ToolPipeline,
+            ConnectorsService,
+            OAuthFlow,
+            ConversationToolInfo,
+        ],
+    })
+], ToolsModule);
+export { ToolsModule };

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;
 }