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

package/dist/tools/credentials.d.ts

@@ -1,10 +1,11 @@
 import type { AuthInjection } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
-import { type Transaction } from "kysely";
-import type { KernelConfig } from "../config/schema.js";
 import { type Keyring } from "../ctx/secrets.js";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
 import type { KernelLogger } from "../log.js";
 import { type OAuthClientRecord, type OAuthTokenRecord } from "./oauth/tokens.js";
 export type Ownership = "org" | "personal";
@@ -75,52 +76,48 @@ export declare class CredentialMissing extends ApiError {
  * 删除某账号在该组织所有连接器上的个人凭据（`credentials:app:<connectorId>:user:<accountId>`，含已删除连接器残留的），
  * 成员离职时在其事务内调用（不解密，不需要密钥环）。返回删除条数。
  */
-export declare function clearAccountCredentials(db: KernelDb | Transaction<KernelDatabase>, orgId: string, accountId: string): Promise<number>;
-/** OAuth 刷新所需的依赖（锁在 Redis，往返限时与本机 http 放行取自配置）。 */
-export interface CredentialsOAuthDeps {
-    redis: Redis;
-    config: () => KernelConfig;
-}
+export declare function clearAccountCredentials(db: KernelSchemaDb, orgId: string, accountId: string): Promise<number>;
 /**
  * 连接器凭据：信封加密存入 capybara.secrets，解密后只在构造注入头时出现。OAuth 连接器的 token 也存在这里
- * （个人 / 组织键，同静态凭据），OAuth 客户端存组织级的 `:client` 键；刷新见 oauth/tokens.ts。
+ * （个人 / 组织键，同静态凭据），OAuth 客户端存组织级的 `:client` 键；刷新见 oauth/tokens.ts（锁在 Redis，
+ * 往返限时与本机 http 放行取自配置）。Writes and deletes run on the context's handle (`KernelDb`): inside a
+ * caller's `@Transactional` they join its transaction (they live and die with the connector row and audit).
  */
 export declare class Credentials {
     private readonly db;
     private readonly keyring;
     private readonly log;
     private readonly tokens;
-    constructor(db: KernelDb, keyring: Keyring, log: KernelLogger, oauth?: CredentialsOAuthDeps);
+    constructor(db: KernelDb, keyring: Keyring, log: KernelLogger, config: Pick<KernelConfigService, "get">, locks: Pick<LockService, "lease" | "releaseIf" | "renew">, redis: Pick<Redis, "exists">);
     private oauth;
     /** 读一条 JSON 凭据；不存在 / 解不开 → null（日志不带内容）。 */
     private readJson;
     /** OAuth 客户端与令牌里的密钥值登记日志打码（logger 只收 ≥ 12 的值）。 */
     private registerSecrets;
     oauthClient(orgId: string, connectorId: string): Promise<OAuthClientRecord | null>;
-    setOAuthClient(orgId: string, connectorId: string, client: OAuthClientRecord, trx?: Transaction<KernelDatabase>): Promise<void>;
+    setOAuthClient(orgId: string, connectorId: string, client: OAuthClientRecord): Promise<void>;
     oauthTokens(orgId: string, connectorId: string, owner: CredentialOwner): Promise<OAuthTokenRecord | null>;
-    setOAuthTokens(orgId: string, connectorId: string, owner: CredentialOwner, rec: OAuthTokenRecord, trx?: Transaction<KernelDatabase>): Promise<void>;
+    setOAuthTokens(orgId: string, connectorId: string, owner: CredentialOwner, rec: OAuthTokenRecord): Promise<void>;
+    /** The secrets store on the context's handle (the caller's transaction, else the pool). */
     private secrets;
     /**
      * 按认证方式校验凭据形状与归属；错误（`validation_failed`）只含路径与英文说明，不回显值。
      * 连接器创建时先用它校验、再拿内存中的值连接，连上之后才落库。
      */
     validate(auth: ConnectorAuth, owner: CredentialOwner, value: unknown): asserts value is StaticSecret;
-    setStatic(orgId: string, connectorId: string, auth: ConnectorAuth, owner: CredentialOwner, value: StaticSecret, 
-    /** 传入时在调用方事务内写入（与连接器行 / 审计同生共死）。 */
-    trx?: Transaction<KernelDatabase>): Promise<void>;
-    clear(orgId: string, connectorId: string, owner: CredentialOwner, trx?: Transaction<KernelDatabase>): Promise<void>;
+    setStatic(orgId: string, connectorId: string, auth: ConnectorAuth, owner: CredentialOwner, value: StaticSecret): Promise<void>;
+    clear(orgId: string, connectorId: string, owner: CredentialOwner): Promise<void>;
     /** 删除某连接器的全部凭据（组织凭据与所有成员的个人凭据），连接器删除时调用。 */
-    clearConnector(orgId: string, connectorId: string, trx?: Transaction<KernelDatabase>): Promise<void>;
+    clearConnector(orgId: string, connectorId: string): Promise<void>;
     /** 删除某账号在该组织所有连接器上的个人凭据，见 {@link clearAccountCredentials}。 */
-    clearAccount(orgId: string, accountId: string, trx?: Transaction<KernelDatabase>): Promise<number>;
+    clearAccount(orgId: string, accountId: string): Promise<number>;
     /**
      * 持有该连接器个人凭据的**现任成员**（不解密），按凭据最近写入时间倒序（保存静态凭据、OAuth 连接与刷新 token
      * 都会更新写入时间），最多 `limit` 个。漂移检查用它挑个人凭据型连接器的凭据。
      */
     personalHolders(orgId: string, connectorId: string, limit: number): Promise<string[]>;
     /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
-    status(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string, trx?: Transaction<KernelDatabase>): Promise<"connected" | "missing">;
+    status(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string): Promise<"connected" | "missing">;
     /** 返回本次请求要注入的头 / 查询参数；缺凭据抛 CredentialMissing。 */
     injection(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string): Promise<AuthInjection>;
     /**

package/dist/tools/credentials.js

@@ -1,7 +1,21 @@
+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 } from "@nestjs/common";
 import { sql } from "kysely";
 import { z } from "zod";
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_LOGGER, KEYRING, REDIS } from "../infra/tokens.js";
 import { oauthHttpOptions } from "./oauth/discovery.js";
 import { OAuthReconnectRequired, OAuthTokens, } from "./oauth/tokens.js";
 import { injectionSecrets } from "./redact.js";
@@ -69,30 +83,28 @@ export async function clearAccountCredentials(db, orgId, accountId) {
 }
 /**
  * 连接器凭据：信封加密存入 capybara.secrets，解密后只在构造注入头时出现。OAuth 连接器的 token 也存在这里
- * （个人 / 组织键，同静态凭据），OAuth 客户端存组织级的 `:client` 键；刷新见 oauth/tokens.ts。
+ * （个人 / 组织键，同静态凭据），OAuth 客户端存组织级的 `:client` 键；刷新见 oauth/tokens.ts（锁在 Redis，
+ * 往返限时与本机 http 放行取自配置）。Writes and deletes run on the context's handle (`KernelDb`): inside a
+ * caller's `@Transactional` they join its transaction (they live and die with the connector row and audit).
  */
-export class Credentials {
+let Credentials = class Credentials {
     db;
     keyring;
     log;
     tokens;
-    constructor(db, keyring, log, oauth) {
+    constructor(db, keyring, log, config, locks, redis) {
         this.db = db;
         this.keyring = keyring;
         this.log = log;
-        if (oauth) {
-            const store = {
-                readClient: (orgId, connectorId) => this.oauthClient(orgId, connectorId),
-                readTokens: (orgId, connectorId, owner) => this.oauthTokens(orgId, connectorId, owner),
-                writeTokens: (orgId, connectorId, owner, rec) => this.setOAuthTokens(orgId, connectorId, owner, rec),
-                deleteTokens: (orgId, connectorId, owner) => this.clear(orgId, connectorId, owner),
-            };
-            this.tokens = new OAuthTokens(store, oauth.redis, () => oauthHttpOptions(oauth.config()), log);
-        }
+        const store = {
+            readClient: (orgId, connectorId) => this.oauthClient(orgId, connectorId),
+            readTokens: (orgId, connectorId, owner) => this.oauthTokens(orgId, connectorId, owner),
+            writeTokens: (orgId, connectorId, owner, rec) => this.setOAuthTokens(orgId, connectorId, owner, rec),
+            deleteTokens: (orgId, connectorId, owner) => this.clear(orgId, connectorId, owner),
+        };
+        this.tokens = new OAuthTokens(store, locks, redis, () => oauthHttpOptions(config.get()), log);
     }
     oauth() {
-        if (!this.tokens)
-            throw new Error("credentials: OAuth is not configured");
         return this.tokens;
     }
     /** 读一条 JSON 凭据；不存在 / 解不开 → null（日志不带内容）。 */
@@ -119,9 +131,9 @@ export class Credentials {
         this.registerSecrets([v.clientSecret, v.registration?.accessToken]);
         return v;
     }
-    async setOAuthClient(orgId, connectorId, client, trx) {
+    async setOAuthClient(orgId, connectorId, client) {
         this.registerSecrets([client.clientSecret, client.registration?.accessToken]);
-        await this.secrets(trx).set(orgId, clientKey(connectorId), JSON.stringify(client));
+        await this.secrets().set(orgId, clientKey(connectorId), JSON.stringify(client));
     }
     async oauthTokens(orgId, connectorId, owner) {
         const v = (await this.readJson(orgId, keyOf(connectorId, owner), connectorId));
@@ -130,12 +142,13 @@ export class Credentials {
         this.registerSecrets([v.access_token, v.refresh_token]);
         return v;
     }
-    async setOAuthTokens(orgId, connectorId, owner, rec, trx) {
+    async setOAuthTokens(orgId, connectorId, owner, rec) {
         this.registerSecrets([rec.access_token, rec.refresh_token]);
-        await this.secrets(trx).set(orgId, keyOf(connectorId, owner), JSON.stringify(rec));
+        await this.secrets().set(orgId, keyOf(connectorId, owner), JSON.stringify(rec));
     }
-    secrets(db = this.db) {
-        return createSecrets(db, this.keyring, NAMESPACE);
+    /** The secrets store on the context's handle (the caller's transaction, else the pool). */
+    secrets() {
+        return createSecrets(this.db.db, this.keyring, NAMESPACE);
     }
     /**
      * 按认证方式校验凭据形状与归属；错误（`validation_failed`）只含路径与英文说明，不回显值。
@@ -189,19 +202,17 @@ export class Credentials {
             throw fail(r.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })));
         }
     }
-    async setStatic(orgId, connectorId, auth, owner, value, 
-    /** 传入时在调用方事务内写入（与连接器行 / 审计同生共死）。 */
-    trx) {
+    async setStatic(orgId, connectorId, auth, owner, value) {
         this.validate(auth, owner, value);
-        await this.secrets(trx).set(orgId, keyOf(connectorId, owner), JSON.stringify(value));
+        await this.secrets().set(orgId, keyOf(connectorId, owner), JSON.stringify(value));
     }
-    async clear(orgId, connectorId, owner, trx) {
-        await this.secrets(trx).delete(orgId, keyOf(connectorId, owner));
+    async clear(orgId, connectorId, owner) {
+        await this.secrets().delete(orgId, keyOf(connectorId, owner));
     }
     /** 删除某连接器的全部凭据（组织凭据与所有成员的个人凭据），连接器删除时调用。 */
-    async clearConnector(orgId, connectorId, trx) {
+    async clearConnector(orgId, connectorId) {
         const prefix = orgKey(connectorId).slice(0, -"org".length);
-        await (trx ?? this.db)
+        await this.db
             .deleteFrom("secrets")
             .where("namespace", "=", NAMESPACE)
             .where("org_id", "=", orgId)
@@ -209,8 +220,8 @@ export class Credentials {
             .execute();
     }
     /** 删除某账号在该组织所有连接器上的个人凭据，见 {@link clearAccountCredentials}。 */
-    async clearAccount(orgId, accountId, trx) {
-        return clearAccountCredentials(trx ?? this.db, orgId, accountId);
+    async clearAccount(orgId, accountId) {
+        return clearAccountCredentials(this.db.db, orgId, accountId);
     }
     /**
      * 持有该连接器个人凭据的**现任成员**（不解密），按凭据最近写入时间倒序（保存静态凭据、OAuth 连接与刷新 token
@@ -225,11 +236,11 @@ export class Credentials {
       WHERE s.namespace = ${NAMESPACE} AND s.org_id = ${orgId}
         AND left(s.key, ${prefix.length}) = ${prefix}
       ORDER BY s.updated_at DESC, m.account_id
-      LIMIT ${limit}`.execute(this.db);
+      LIMIT ${limit}`.execute(this.db.db);
         return rows.rows.map((r) => r.account_id);
     }
     /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
-    async status(orgId, connectorId, auth, accountId, trx) {
+    async status(orgId, connectorId, auth, accountId) {
         if (auth.type === "none")
             return "connected";
         // 客户端凭据流：有客户端即可按需取 token
@@ -238,7 +249,7 @@ export class Credentials {
             : auth.ownership === "personal"
                 ? userKey(connectorId, accountId)
                 : orgKey(connectorId);
-        const row = await (trx ?? this.db)
+        const row = await this.db
             .selectFrom("secrets")
             .select("key")
             .where("namespace", "=", NAMESPACE)
@@ -348,4 +359,14 @@ export class Credentials {
             }
         }
     }
-}
+};
+Credentials = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KEYRING)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(LockService)),
+    __param(5, Inject(REDIS))
+], Credentials);
+export { Credentials };

package/dist/tools/display-names.d.ts

@@ -0,0 +1,9 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * The display names of plugins, for naming their extensions' tools (`<display name> [<tool>]`,
+ * tool naming spec §7): the live catalog item's `displayName`, else the plugin name in both
+ * languages (a bootstrap or uploaded plugin without a catalog item, or one without a display name).
+ * Display only.
+ */
+export declare function pluginDisplayNames(db: KernelSchemaDb, names: readonly string[]): Promise<Map<string, LocalizedName>>;

package/dist/tools/display-names.js

@@ -0,0 +1,24 @@
+/**
+ * The display names of plugins, for naming their extensions' tools (`<display name> [<tool>]`,
+ * tool naming spec §7): the live catalog item's `displayName`, else the plugin name in both
+ * languages (a bootstrap or uploaded plugin without a catalog item, or one without a display name).
+ * Display only.
+ */
+export async function pluginDisplayNames(db, names) {
+    const unique = [...new Set(names)];
+    const out = new Map(unique.map((n) => [n, { zh: n, en: n }]));
+    if (unique.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("catalog_items")
+        .select(["name", "display_name"])
+        .where("name", "in", unique)
+        .where("deleted_at", "is", null)
+        .execute();
+    for (const r of rows) {
+        const d = r.display_name;
+        if (d && typeof d.zh === "string" && typeof d.en === "string" && d.zh !== "" && d.en !== "")
+            out.set(r.name, { zh: d.zh, en: d.en });
+    }
+    return out;
+}

package/dist/tools/drift.d.ts

@@ -1,30 +1,11 @@
 import { type AuthInjection, type Logger, type ToolSpec } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import type { Maintenance } from "../runtime/maintenance.js";
-import { type Credentials } from "./credentials.js";
-import { type ToolRegistry } from "./registry.js";
-/**
- * 工具定义漂移检测（spec 7.3：新增 / 变化的工具在组织管理员复核前不可用，防 rug-pull / 工具投毒）。
- *
- * 与上次快照比对：新增 → 插入 `pending_review`；定义（spec_hash 或来源）变化 → `pending_review`，新定义存
- * `pending_spec`，旧定义留在 `spec` 供对比，复核通过才采用；消失 → `disabled` 并记 `missing_since`（行保留，
- * 又出现时按新增处理）。定义不合规（key 不合法等）的工具只能停用：新增时直接停用；复核过的工具变成不合规
- * 定义时新定义同样只进 `pending_spec`（停用，approve 被拒），`spec` 始终是上次复核通过的定义。
- * 从未复核过的工具（`reviewed_at` 为空）没有可比的旧定义：定义再变时直接替换 `spec`（仍待复核），不产生 pending。
- * 连接器从未拍过快照（`tools_synced_at` 为空且没有工具行，即 OAuth 授权码连接器安装时不 listTools，A16）时，
- * 首个快照按安装处理（直接启用）。
- *
- * 触发：维护队列的周期扫描（`tools.driftIntervalHours`）、连接器在会话中报告工具清单变了（MCP
- * `notifications/tools/list_changed`）、管理员手动刷新（`ConnectorsService.refresh`，走同一套比对）。
- * 授权（`tool_grants` / `conversation_tool_grants`）按 spec_hash 比对（D8），复核通过采用新指纹后旧授权自然失效。
- */
-/** 周期扫描：任务名与 job scheduler id（不含 `:`）。 */
-export declare const DRIFT_SCAN_JOB = "drift-scan";
-export declare const DRIFT_SCHEDULER_ID = "drift-scan-interval";
-/** 单个连接器的漂移检查任务名。 */
-export declare const DRIFT_CONNECTOR_JOB = "drift-connector";
+import type { Queue } from "bullmq";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Credentials } from "./credentials.js";
+import { ToolRegistry } from "./registry.js";
+export { DRIFT_CONNECTOR_JOB, DRIFT_SCAN_JOB, DRIFT_SCHEDULER_ID } from "./job-ids.js";
 /**
  * list_changed 触发的检查：jobId 按连接器与分钟桶去重（同一分钟内多次通知只检查一次；connectorId 为 UUID，不含 `:`）。
  */
@@ -46,7 +27,6 @@ export type DriftCheckResult = {
     status: "skipped";
     reason: "not_found" | "inactive" | "no_connector" | "no_credential" | "connect_failed";
 };
-type Trx = Transaction<KernelDatabase>;
 type ToolSource = "connector" | "resources";
 /** 快照中被停用 / 跳过的工具及英文原因。 */
 export interface ToolIssue {
@@ -87,19 +67,26 @@ export declare function snapshot(slug: string, specs: unknown, resources: boolea
 export declare function sanitizeToolTitle(raw: unknown): string | undefined;
 /** 工具当前不能启用的原因（视图、启用与复核校验共用）。 */
 export declare function toolIssue(slug: string, spec: ToolSpec): string | null;
-export interface ToolDriftDeps {
-    db: KernelDb;
-    registry: Pick<ToolRegistry, "findConnector">;
-    credentials: Pick<Credentials, "injection" | "onUnauthorized" | "personalHolders">;
-    config: () => KernelConfig;
-    log: Logger;
-    /** 维护队列（登记周期扫描与检查任务的处理函数；不给时只能同步调用 `check`）。 */
-    maintenance?: Pick<Maintenance, "add" | "handle" | "schedule">;
+/** The data of a `drift-connector` job. */
+export interface DriftConnectorJobData {
+    orgId: string;
+    connectorId: string;
+    trigger: DriftTrigger;
 }
 export declare class ToolDrift {
-    private readonly d;
-    constructor(d: ToolDriftDeps);
-    private intervalMs;
+    private readonly db;
+    private readonly registry;
+    private readonly credentials;
+    private readonly config;
+    private readonly log;
+    /** The maintenance queue's producer (`drift-connector` jobs). */
+    private readonly queue;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, registry: Pick<ToolRegistry, "findConnector">, credentials: Pick<Credentials, "injection" | "onUnauthorized" | "personalHolders">, config: Pick<KernelConfigService, "get">, log: Logger, 
+    /** The maintenance queue's producer (`drift-connector` jobs). */
+    queue: Pick<Queue, "add">, txHost: TransactionHost);
+    /** The scan period (`tools.driftIntervalHours`). */
+    intervalMs(): number;
     /**
      * 打开一次会话拉工具清单，无论成败都关闭会话；会话带 `listResources` 即视为支持 resources。
      * 清单里回显的凭据按本次注入的值打码（见 redact.ts）。凭据缺失原样抛 `credential.missing`；
@@ -112,10 +99,10 @@ export declare class ToolDrift {
         resources: boolean;
     }>;
     /**
-     * 把新快照与当前工具行比对并写入（调用方已在事务内锁住连接器行）；返回按名排序的变化。
+     * 把新快照与当前工具行比对并写入（调用方已在事务内锁住连接器行：`mandatory`）；返回按名排序的变化。
      * 规则见文件头。待复核的新定义也写进 `tool_specs`（内容寻址，只增不改）。
      */
-    apply(t: Trx, app: {
+    apply(app: {
         id: string;
         tools_synced_at: Date | null;
     }, rows: SnapshotRow[]): Promise<DriftChanges>;
@@ -128,6 +115,8 @@ export declare class ToolDrift {
      * 连不上 / 都失败 → 跳过（不改快照，下个周期或下次通知再查）。
      */
     check(orgId: string, connectorId: string, trigger: DriftTrigger): Promise<DriftCheckResult>;
+    /** The locked compare-and-write of {@link check}, audited when something changed. */
+    private applyChecked;
     /**
      * 连接器在会话中报告工具清单变了：投递一次该连接器的检查（jobId 按分钟桶去重）。投递失败只记日志。
      */
@@ -138,4 +127,3 @@ export declare class ToolDrift {
      */
     scan(): Promise<number>;
 }
-export {};