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

package/dist/tools/job-ids.js

@@ -0,0 +1,15 @@
+// The tools' job names and the retired scheduler ids: a leaf module (no service imports), read by
+// the maintenance queue's retirement list.
+/** The periodic drift scan (`@LockedInterval`, tools/jobs.ts). */
+export const DRIFT_SCAN_JOB = "drift-scan";
+/** The BullMQ repeatable scheduler the scan had before it became `@LockedInterval` (retired). */
+export const DRIFT_SCHEDULER_ID = "drift-scan-interval";
+/**
+ * 单个连接器的漂移检查任务名（维护队列上的一次性任务：生产方是 `ToolDrift`，消费方是
+ * `MaintenanceProcessor`）。
+ */
+export const DRIFT_CONNECTOR_JOB = "drift-connector";
+/** The hourly cleanup of expired tool output archives (`@LockedCron`, tools/jobs.ts). */
+export const OUTPUT_CLEANUP_JOB = "output-cleanup";
+/** The BullMQ repeatable scheduler the cleanup had before it became `@LockedCron` (retired). */
+export const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";

package/dist/tools/jobs.d.ts

@@ -0,0 +1,24 @@
+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 { ToolDrift } from "./drift.js";
+/**
+ * The tools' periodic jobs, each run once per tick across replicas: the tool drift scan
+ * (`drift-scan`, every `tools.driftIntervalHours` and once right after the start, as the old
+ * repeatable scheduler's first run: `@LockedInterval` with `runOnStart`; a repeated scan in the
+ * same period enqueues nothing new, its job ids are per period) and the hourly cleanup of expired
+ * tool output archives (`output-cleanup`: `@LockedCron`).
+ */
+export declare class ToolJobs {
+    private readonly drift;
+    private readonly db;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(drift: Pick<ToolDrift, "scan">, db: KernelDb, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    /** Enqueues a drift check of every active connector not checked in this period. */
+    scanDrift(): Promise<void>;
+    /** Deletes expired tool output archives (in batches, no long transaction). */
+    cleanupOutputs(): Promise<void>;
+}

package/dist/tools/jobs.js

@@ -0,0 +1,69 @@
+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 { 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 { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { LockedInterval } from "../infra/schedule/locked-interval.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ToolDrift } from "./drift.js";
+import { DRIFT_SCAN_JOB, OUTPUT_CLEANUP_JOB } from "./job-ids.js";
+import { deleteExpiredOutputs } from "./outputs.js";
+/**
+ * The tools' periodic jobs, each run once per tick across replicas: the tool drift scan
+ * (`drift-scan`, every `tools.driftIntervalHours` and once right after the start, as the old
+ * repeatable scheduler's first run: `@LockedInterval` with `runOnStart`; a repeated scan in the
+ * same period enqueues nothing new, its job ids are per period) and the hourly cleanup of expired
+ * tool output archives (`output-cleanup`: `@LockedCron`).
+ */
+let ToolJobs = class ToolJobs {
+    drift;
+    db;
+    config;
+    lockService;
+    log;
+    constructor(drift, db, config, lockService, log) {
+        this.drift = drift;
+        this.db = db;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    /** Enqueues a drift check of every active connector not checked in this period. */
+    async scanDrift() {
+        const n = await this.drift.scan();
+        if (n > 0)
+            this.log.info("tool drift checks enqueued", { count: n });
+    }
+    /** Deletes expired tool output archives (in batches, no long transaction). */
+    async cleanupOutputs() {
+        const n = await deleteExpiredOutputs(this.db.db);
+        if (n > 0)
+            this.log.info("expired tool outputs deleted", { count: n });
+    }
+};
+__decorate([
+    LockedInterval(DRIFT_SCAN_JOB, (c) => c.tools.driftIntervalHours * 3_600_000, {
+        runOnStart: true,
+    })
+], ToolJobs.prototype, "scanDrift", null);
+__decorate([
+    LockedCron("0 * * * *", { name: OUTPUT_CLEANUP_JOB })
+], ToolJobs.prototype, "cleanupOutputs", null);
+ToolJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(ToolDrift)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], ToolJobs);
+export { ToolJobs };

package/dist/tools/legacy-data.d.ts

@@ -0,0 +1,34 @@
+import { type AgentDefinition } from "../agents/definition.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { KernelLogger } from "../log.js";
+import { type LegacyScope } from "./legacy-keys.js";
+/**
+ * Stored release-candidate tool keys (tool naming spec §8): the scope that reads an rc
+ * `<x>__<tool>` key in an org, the stored-definition readers that use it, and the startup notice
+ * for the rows migration 0063 could not map. No in-process state: each call reads PostgreSQL.
+ */
+/**
+ * What an rc `<x>__<tool>` key can name in `orgId`: the org's live connector slugs and the
+ * deployment's extension names (installed ones and config-declared ones, which claim their name
+ * in `extension_name_owners`). Migration 0063 reads the same two sources.
+ */
+export declare function loadLegacyScope(db: KernelSchemaDb, orgId: string): Promise<LegacyScope>;
+/**
+ * A stored agent definition of `orgId` with every rc key it can map read as the current key
+ * ({@link normalizeStoredDefinition}); the scope is read only when the definition holds an rc
+ * `<x>__<tool>` key.
+ */
+export declare function normalizeStoredDefinitionIn(db: KernelSchemaDb, orgId: string, def: unknown): Promise<AgentDefinition>;
+/** A stored agent template (or any template-shaped value) of `orgId` in current keys. */
+export declare function normalizeTemplateIn<T>(db: KernelSchemaDb, orgId: string, t: T): Promise<T>;
+/**
+ * Rows still holding an rc tool key after migration 0063: grants and pending approvals and
+ * questions it could not map (an ambiguous or unknown `<x>__<tool>`). Read-only.
+ */
+export declare function countLegacyToolKeys(db: KernelSchemaDb): Promise<number>;
+/**
+ * The startup notice (spec §8.2): one WARN `tools.legacy_key_unmapped` with the count of rows
+ * still holding an rc key, only when there are any. A grant that no longer matches stops applying
+ * (the person is asked again), so this is a notice, not a failure.
+ */
+export declare function warnLegacyToolKeys(db: KernelSchemaDb, log: Pick<KernelLogger, "warn">): Promise<void>;

package/dist/tools/legacy-data.js

@@ -0,0 +1,76 @@
+import { sql } from "kysely";
+import { needsLegacyScope, normalizeStoredDefinition, normalizeToolKeys, } from "../agents/definition.js";
+import { LEGACY_BUILTINS } from "./legacy-keys.js";
+/**
+ * Stored release-candidate tool keys (tool naming spec §8): the scope that reads an rc
+ * `<x>__<tool>` key in an org, the stored-definition readers that use it, and the startup notice
+ * for the rows migration 0063 could not map. No in-process state: each call reads PostgreSQL.
+ */
+/**
+ * What an rc `<x>__<tool>` key can name in `orgId`: the org's live connector slugs and the
+ * deployment's extension names (installed ones and config-declared ones, which claim their name
+ * in `extension_name_owners`). Migration 0063 reads the same two sources.
+ */
+export async function loadLegacyScope(db, orgId) {
+    const [connectors, installs, owners] = await Promise.all([
+        db
+            .selectFrom("connectors")
+            .select(["id", "slug"])
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .execute(),
+        db.selectFrom("extension_installs").select("name").execute(),
+        db.selectFrom("extension_name_owners").select("name").execute(),
+    ]);
+    return {
+        connectorSlugs: new Set(connectors.map((r) => r.slug)),
+        connectorSlugById: new Map(connectors.map((r) => [r.id, r.slug])),
+        extensionNames: new Set([...installs, ...owners].map((r) => r.name)),
+    };
+}
+/**
+ * A stored agent definition of `orgId` with every rc key it can map read as the current key
+ * ({@link normalizeStoredDefinition}); the scope is read only when the definition holds an rc
+ * `<x>__<tool>` key.
+ */
+export async function normalizeStoredDefinitionIn(db, orgId, def) {
+    return normalizeStoredDefinition(def, needsLegacyScope(def) ? await loadLegacyScope(db, orgId) : undefined);
+}
+/** A stored agent template (or any template-shaped value) of `orgId` in current keys. */
+export async function normalizeTemplateIn(db, orgId, t) {
+    return normalizeToolKeys(t, needsLegacyScope(t) ? await loadLegacyScope(db, orgId) : undefined);
+}
+/**
+ * The SQL test for an rc key, the predicate of migration 0063's partial indexes (so the count
+ * below reads only those, nearly empty, indexes): an old builtin name, or `<x>__<tool>` not in the
+ * current `mcp__` / `plugin__` format.
+ */
+const legacyKeySql = (col) => sql `(${col} = ANY (ARRAY[${sql.join(Object.keys(LEGACY_BUILTINS).map((k) => sql.lit(k)))}]::text[]) OR (${col} ~ '^[a-z0-9][a-z0-9_-]*__.' AND ${col} !~ '^(mcp|plugin)__'))`;
+/**
+ * Rows still holding an rc tool key after migration 0063: grants and pending approvals and
+ * questions it could not map (an ambiguous or unknown `<x>__<tool>`). Read-only.
+ */
+export async function countLegacyToolKeys(db) {
+    const r = await sql `
+    SELECT
+      (SELECT count(*) FROM capybara.tool_grants WHERE ${legacyKeySql(sql.ref("tool_key"))})
+      + (SELECT count(*) FROM capybara.conversation_tool_grants
+         WHERE ${legacyKeySql(sql.ref("tool_key"))})
+      + (SELECT count(*) FROM capybara.approvals
+         WHERE status = 'pending' AND ${legacyKeySql(sql.ref("tool_key"))})
+      + (SELECT count(*) FROM capybara.questions
+         WHERE status = 'pending' AND ${legacyKeySql(sql.raw("(spec->>'toolKey')"))})
+      AS n
+  `.execute(db);
+    return Number(r.rows[0]?.n ?? 0);
+}
+/**
+ * The startup notice (spec §8.2): one WARN `tools.legacy_key_unmapped` with the count of rows
+ * still holding an rc key, only when there are any. A grant that no longer matches stops applying
+ * (the person is asked again), so this is a notice, not a failure.
+ */
+export async function warnLegacyToolKeys(db, log) {
+    const count = await countLegacyToolKeys(db);
+    if (count > 0)
+        log.warn("tools.legacy_key_unmapped", { count });
+}

package/dist/tools/legacy-keys.d.ts

@@ -0,0 +1,51 @@
+import { type BuiltinName } from "./builtin-names.js";
+/**
+ * The release-candidate builtin tool names (tool naming spec §8.1). FROZEN: it describes the names
+ * of the 0.1.0 release candidates and never grows. Old keys stay in logs, recordings and stored
+ * configuration; this map is how the kernel reads them. `check:terms` exempts this file.
+ */
+export interface LegacyBuiltin {
+    /** The new name. */
+    name: BuiltinName;
+    /** Old parameter name -> new parameter name (only the renamed ones). */
+    params: Readonly<Record<string, string>>;
+    /** New parameters whose value is in milliseconds where the old one was in seconds (× 1000). */
+    msParams?: readonly string[];
+}
+export declare const LEGACY_BUILTINS: Readonly<Record<string, LegacyBuiltin>>;
+/** Is `key` a release-candidate builtin name? */
+export declare const isLegacyBuiltinKey: (key: string) => boolean;
+/** What a connector slug / extension name can be, to read an old `<x>__<tool>` key. */
+export interface LegacyScope {
+    connectorSlugs: ReadonlySet<string>;
+    extensionNames: ReadonlySet<string>;
+    /**
+     * Connector id -> slug, for reading a stored definition's connector refs when a key is
+     * ambiguous (a slug that is also an extension name); optional.
+     */
+    connectorSlugById?: ReadonlyMap<string, string>;
+}
+/**
+ * Is `key` an rc `<x>__<tool>` key, which only a {@link LegacyScope} can map? Keys in the current
+ * format (`mcp__…`, `plugin__…`) never are.
+ */
+export declare const isLegacyPrefixedKey: (key: string) => boolean;
+/**
+ * The current key of a release-candidate key: a builtin by the frozen map; `<x>__<tool>` becomes
+ * `mcp__x__tool` when `x` is only a connector slug in `scope`, `plugin__x__tool` when only an
+ * extension name, else null (ambiguous, unknown, or not an old key; a key in the current format
+ * is never mapped again).
+ */
+export declare function legacyToolKey(key: string, scope?: LegacyScope): string | null;
+/** The input of an old builtin call in the current parameter names (seconds -> milliseconds). */
+export declare function legacyToolInput(oldKey: string, input: unknown): unknown;
+/** The model-visible hint for a call to an old builtin key; null for any other key. */
+export declare function legacyHint(key: string): string | null;
+/**
+ * The current key(s) an rc key stands for, to name in a refusal when a definition is saved with
+ * it: a builtin's new name; for `<x>__<tool>`, the candidates among `known` (the agent's tool
+ * keys), else both `mcp__<x>__<tool>` and `plugin__<x>__<tool>`. Empty when `key` is no rc key.
+ */
+export declare function legacyKeyCandidates(key: string, known?: ReadonlySet<string>): string[];
+/** The refusal text for saving rc key `key` (null when it is none): names the new key(s). */
+export declare function legacyKeySaveText(key: string, known?: ReadonlySet<string>): string | null;

package/dist/tools/legacy-keys.js

@@ -0,0 +1,115 @@
+import { BUILTIN } from "./builtin-names.js";
+export const LEGACY_BUILTINS = Object.freeze({
+    sandbox_bash: {
+        name: BUILTIN.Bash,
+        params: { timeoutSeconds: "timeout" },
+        msParams: ["timeout"],
+    },
+    sandbox_read: { name: BUILTIN.Read, params: { path: "file_path" } },
+    sandbox_write: { name: BUILTIN.Write, params: { path: "file_path" } },
+    sandbox_edit: {
+        name: BUILTIN.Edit,
+        params: {
+            path: "file_path",
+            oldText: "old_string",
+            newText: "new_string",
+            replaceAll: "replace_all",
+        },
+    },
+    sandbox_glob: { name: BUILTIN.Glob, params: {} },
+    sandbox_grep: { name: BUILTIN.Grep, params: { ignoreCase: "-i" } },
+    sandbox_deliver: { name: BUILTIN.Deliver, params: { path: "file_path" } },
+    skill_load: { name: BUILTIN.Skill, params: { name: "skill" } },
+    skill_write: { name: BUILTIN.SkillWrite, params: {} },
+    ask_user: { name: BUILTIN.AskUserQuestion, params: {} },
+    read_tool_output: { name: BUILTIN.ReadToolOutput, params: {} },
+    tool_search: { name: BUILTIN.ToolSearch, params: { limit: "max_results" } },
+    agent: { name: BUILTIN.Agent, params: {} },
+});
+/** Is `key` a release-candidate builtin name? */
+export const isLegacyBuiltinKey = (key) => Object.hasOwn(LEGACY_BUILTINS, key);
+/** A key in the current format for connector and extension tools (`mcp__…`, `plugin__…`). */
+const CURRENT_PREFIXED_RE = /^(mcp|plugin)__/;
+/** An rc connector or extension key `<x>__<tool>` (the SQL of migration 0063 uses the same test). */
+const LEGACY_PREFIXED_RE = /^[a-z0-9][a-z0-9_-]*__./;
+/**
+ * Is `key` an rc `<x>__<tool>` key, which only a {@link LegacyScope} can map? Keys in the current
+ * format (`mcp__…`, `plugin__…`) never are.
+ */
+export const isLegacyPrefixedKey = (key) => LEGACY_PREFIXED_RE.test(key) && !CURRENT_PREFIXED_RE.test(key);
+/**
+ * The current key of a release-candidate key: a builtin by the frozen map; `<x>__<tool>` becomes
+ * `mcp__x__tool` when `x` is only a connector slug in `scope`, `plugin__x__tool` when only an
+ * extension name, else null (ambiguous, unknown, or not an old key; a key in the current format
+ * is never mapped again).
+ */
+export function legacyToolKey(key, scope) {
+    if (isLegacyBuiltinKey(key))
+        return LEGACY_BUILTINS[key].name;
+    if (scope === undefined || !isLegacyPrefixedKey(key))
+        return null;
+    const i = key.indexOf("__");
+    if (i <= 0 || i + 2 >= key.length)
+        return null;
+    const head = key.slice(0, i);
+    const tool = key.slice(i + 2);
+    const connector = scope.connectorSlugs.has(head);
+    const extension = scope.extensionNames.has(head);
+    if (connector === extension)
+        return null;
+    return connector ? `mcp__${head}__${tool}` : `plugin__${head}__${tool}`;
+}
+/** The input of an old builtin call in the current parameter names (seconds -> milliseconds). */
+export function legacyToolInput(oldKey, input) {
+    if (!isLegacyBuiltinKey(oldKey))
+        return input;
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const { params, msParams } = LEGACY_BUILTINS[oldKey];
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        const next = Object.hasOwn(params, k) ? params[k] : k;
+        out[next] = msParams?.includes(next) === true && typeof v === "number" ? v * 1000 : v;
+    }
+    return out;
+}
+/** The new parameters of the builtins whose parameters were renamed (model-visible hint text). */
+const HINT_PARAMS = {
+    Bash: "command, description, timeout in milliseconds",
+    Read: "file_path, offset, limit",
+    Write: "file_path, content",
+    Edit: "file_path, old_string, new_string, replace_all",
+    Grep: "pattern, path, glob, -i, output_mode, -n, -A, -B, -C, head_limit, offset",
+    Deliver: "file_path, name",
+    Skill: "skill, args",
+    ToolSearch: "query, max_results",
+};
+/** The model-visible hint for a call to an old builtin key; null for any other key. */
+export function legacyHint(key) {
+    if (!isLegacyBuiltinKey(key))
+        return null;
+    const { name } = LEGACY_BUILTINS[key];
+    const params = HINT_PARAMS[name];
+    return `Tool "${key}" no longer exists; it is now "${name}"${params === undefined ? "" : ` (parameters: ${params})`}.`;
+}
+/**
+ * The current key(s) an rc key stands for, to name in a refusal when a definition is saved with
+ * it: a builtin's new name; for `<x>__<tool>`, the candidates among `known` (the agent's tool
+ * keys), else both `mcp__<x>__<tool>` and `plugin__<x>__<tool>`. Empty when `key` is no rc key.
+ */
+export function legacyKeyCandidates(key, known) {
+    if (isLegacyBuiltinKey(key))
+        return [LEGACY_BUILTINS[key].name];
+    if (!isLegacyPrefixedKey(key))
+        return [];
+    const all = [`mcp__${key}`, `plugin__${key}`];
+    const hit = all.filter((k) => known?.has(k) === true);
+    return hit.length > 0 ? hit : all;
+}
+/** The refusal text for saving rc key `key` (null when it is none): names the new key(s). */
+export function legacyKeySaveText(key, known) {
+    const c = legacyKeyCandidates(key, known);
+    if (c.length === 0)
+        return null;
+    return `"${key}" is a release-candidate tool key; use ${c.map((x) => `"${x}"`).join(" or ")}`;
+}

package/dist/tools/naming.d.ts

@@ -1,14 +1,12 @@
 /**
  * 工具命名（Global Constraints）：模型可见的工具 key 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；
- * 插件工具为 `<plugin>__<tool>`，连接器工具为 `<connectorSlug>__<tool>`，内置工具就是其名字本身。
+ * 插件工具为 `plugin__<plugin>__<tool>`，连接器工具为 `mcp__<connectorSlug>__<tool>`（拼与拆见 SDK 的 tool-key.ts），内置工具就是其名字本身。
  * 超长或含非法字符的 key 一律报出来，不截断、不猜。
  */
 export declare const TOOL_KEY_RE: RegExp;
 export declare const TOOL_KEY_MAX = 64;
 /** 连接器 slug：小写字母开头，小写字母 / 数字 / 下划线，最长 24。 */
 export declare const APP_SLUG_RE: RegExp;
-/** 前缀与工具名之间的分隔符。 */
-export declare const KEY_SEPARATOR = "__";
 /**
  * slug 是否合法：除正则外，不得含连续下划线、不得以下划线结尾——否则 `a__b` + `c` 与 `a` + `b__c`
  * 会拼出同一个 key。
@@ -21,7 +19,5 @@ export declare const SLUG_RULE = "Slug must start with a lowercase letter, conta
  * 截到 24 位（再去掉尾部下划线）。推导不出合法 slug（如名称全是中文）时返回 null，由调用方要求显式给出。
  */
 export declare function deriveSlug(name: string): string | null;
-/** 拼 `<prefix>__<name>`。 */
-export declare function toolKey(prefix: string, name: string): string;
 /** key 不合法时返回英文原因，合法时返回 null。 */
 export declare function toolKeyIssue(key: string): string | null;

package/dist/tools/naming.js

@@ -1,14 +1,12 @@
 /**
  * 工具命名（Global Constraints）：模型可见的工具 key 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；
- * 插件工具为 `<plugin>__<tool>`，连接器工具为 `<connectorSlug>__<tool>`，内置工具就是其名字本身。
+ * 插件工具为 `plugin__<plugin>__<tool>`，连接器工具为 `mcp__<connectorSlug>__<tool>`（拼与拆见 SDK 的 tool-key.ts），内置工具就是其名字本身。
  * 超长或含非法字符的 key 一律报出来，不截断、不猜。
  */
 export const TOOL_KEY_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 export const TOOL_KEY_MAX = 64;
 /** 连接器 slug：小写字母开头，小写字母 / 数字 / 下划线，最长 24。 */
 export const APP_SLUG_RE = /^[a-z][a-z0-9_]{0,23}$/;
-/** 前缀与工具名之间的分隔符。 */
-export const KEY_SEPARATOR = "__";
 /**
  * slug 是否合法：除正则外，不得含连续下划线、不得以下划线结尾——否则 `a__b` + `c` 与 `a` + `b__c`
  * 会拼出同一个 key。
@@ -31,10 +29,6 @@ export function deriveSlug(name) {
         .replace(/_+$/, "");
     return isValidSlug(s) ? s : null;
 }
-/** 拼 `<prefix>__<name>`。 */
-export function toolKey(prefix, name) {
-    return `${prefix}${KEY_SEPARATOR}${name}`;
-}
 /** key 不合法时返回英文原因，合法时返回 null。 */
 export function toolKeyIssue(key) {
     if (key.length > TOOL_KEY_MAX) {

package/dist/tools/oauth/flow-paths.d.ts

@@ -0,0 +1,16 @@
+import { ApiError } from "../../errors.js";
+/** 授权回调的路径（`http.publicUrl` + 它 = 注册给授权服务器的 redirect_uri）。 */
+export declare const OAUTH_CALLBACK_PATH = "/api/v1/oauth/callback";
+/** state 的有效期（秒）。 */
+export declare const OAUTH_STATE_TTL_SECONDS = 600;
+/** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
+export declare const OAUTH_BINDING_COOKIE = "cap_oauth";
+/** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
+export declare const DEFAULT_RETURN_PATH = "/settings/connections";
+/** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
+export declare const publicUrlRequired: () => ApiError;
+export declare function callbackUrl(publicUrl: string): string;
+/**
+ * 回跳页面只接受站内相对路径（防开放重定向）：以单个 `/` 开头，不含 `\` 与控制字符，解析后仍在同一个源。
+ */
+export declare function isSafeReturnPath(p: string): boolean;

package/dist/tools/oauth/flow-paths.js

@@ -0,0 +1,38 @@
+import { ApiError } from "../../errors.js";
+// The OAuth connect flow's paths and URL rules: a leaf module (no service imports), so the
+// connectors service can use them without an import cycle through the flow.
+/** 授权回调的路径（`http.publicUrl` + 它 = 注册给授权服务器的 redirect_uri）。 */
+export const OAUTH_CALLBACK_PATH = "/api/v1/oauth/callback";
+/** state 的有效期（秒）。 */
+export const OAUTH_STATE_TTL_SECONDS = 600;
+/** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
+export const OAUTH_BINDING_COOKIE = "cap_oauth";
+/** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
+export const DEFAULT_RETURN_PATH = "/settings/connections";
+/** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
+export const publicUrlRequired = () => new ApiError("validation_failed", "Request validation failed", [
+    {
+        path: "auth",
+        message: "OAuth connectors require http.publicUrl to be configured (it is used to build the OAuth callback URL)",
+    },
+]);
+export function callbackUrl(publicUrl) {
+    return `${publicUrl.replace(/\/+$/, "")}${OAUTH_CALLBACK_PATH}`;
+}
+/**
+ * 回跳页面只接受站内相对路径（防开放重定向）：以单个 `/` 开头，不含 `\` 与控制字符，解析后仍在同一个源。
+ */
+export function isSafeReturnPath(p) {
+    if (p.length > 500 || !p.startsWith("/") || p.startsWith("//"))
+        return false;
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拒绝控制字符
+    if (/[\\\u0000-\u001f\u007f]/.test(p))
+        return false;
+    const base = "https://return.invalid";
+    try {
+        return new URL(p, base).origin === base;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tools/oauth/flow.d.ts

@@ -1,46 +1,40 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
-import type { KernelConfig } from "../../config/schema.js";
-import type { KernelDb } from "../../db/kernel-schema.js";
-import { ApiError } from "../../errors.js";
-import type { Credentials } from "../credentials.js";
-/** 授权回调的路径（`http.publicUrl` + 它 = 注册给授权服务器的 redirect_uri）。 */
-export declare const OAUTH_CALLBACK_PATH = "/api/v1/oauth/callback";
-/** state 的有效期（秒）。 */
-export declare const OAUTH_STATE_TTL_SECONDS = 600;
-/** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
-export declare const OAUTH_BINDING_COOKIE = "cap_oauth";
-/** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
-export declare const DEFAULT_RETURN_PATH = "/settings/connections";
-/** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
-export declare const publicUrlRequired: () => ApiError;
-export declare function callbackUrl(publicUrl: string): string;
-/**
- * 回跳页面只接受站内相对路径（防开放重定向）：以单个 `/` 开头，不含 `\` 与控制字符，解析后仍在同一个源。
- */
-export declare function isSafeReturnPath(p: string): boolean;
+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 { OrgLock } from "../../orgs/org-lock.js";
+import { ConnectorsService } from "../connectors.service.js";
+import { Credentials } from "../credentials.js";
+export { callbackUrl, DEFAULT_RETURN_PATH, isSafeReturnPath, OAUTH_BINDING_COOKIE, OAUTH_CALLBACK_PATH, OAUTH_STATE_TTL_SECONDS, publicUrlRequired, } from "./flow-paths.js";
 /** 一个有效的浏览器绑定值（复用请求里已有的，否则新生成）。 */
 export declare function browserBinding(existing: string | undefined): string;
 /** 回调失败的原因码（放进回跳 URL 的 `oauth_error`；不回显授权服务器的任何文本）。 */
 export type OAuthCallbackError = "state_invalid" | "session_mismatch" | "access_denied" | "provider_error" | "token_exchange_failed" | "issuer_mismatch" | "connector_unavailable";
 /** 首次连接后刷新工具清单最多等这么久再 302（超时则在后台继续，结果照常写入）。 */
 export declare const FIRST_CONNECT_REFRESH_WAIT_MS = 15000;
-export interface OAuthFlowDeps {
-    db: KernelDb;
-    redis: Redis;
-    credentials: Credentials;
-    config: () => KernelConfig;
-    log: Logger;
-    /** 某成员首次成功连接、而连接器还没有工具快照时调用（A16：用该成员的 token 刷新工具清单）。 */
-    onFirstConnect: (orgId: string, connectorId: string, accountId: string) => Promise<void>;
-}
 /**
  * 授权码 + PKCE（S256）连接流程。state 是 32 字节随机串，存 Redis `capk:oauth-state:<state>` 10 分钟、单次有效
  * （GETDEL），内含组织、连接器、发起人、PKCE verifier、redirect_uri、回跳页面与浏览器绑定值的哈希。
  */
 export declare class OAuthFlow {
-    private readonly deps;
-    constructor(deps: OAuthFlowDeps);
+    private readonly db;
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    private readonly orgLock;
+    private readonly redis;
+    private readonly credentials;
+    private readonly config;
+    private readonly log;
+    /** A member's first connection without a tool snapshot refreshes the tools (A16). */
+    private readonly connectors;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock: Pick<OrgLock, "lockAndAuthorize">, redis: Pick<Redis, "set" | "getdel">, credentials: Credentials, config: Pick<KernelConfigService, "get">, log: Logger, 
+    /** A member's first connection without a tool snapshot refreshes the tools (A16). */
+    connectors: Pick<ConnectorsService, "refresh">, txHost: TransactionHost);
+    /** 某成员首次成功连接、而连接器还没有工具快照时（A16：用该成员的 token 刷新工具清单）。 */
+    private onFirstConnect;
     private app;
     /** 生成授权 URL。`binding` 为本浏览器的绑定值（由 controller 写入 Cookie）。 */
     start(orgId: string, connectorId: string, accountId: string, returnTo: string | undefined, binding: string): Promise<{
@@ -60,4 +54,10 @@ export declare class OAuthFlow {
         error?: string | undefined;
         iss?: string | undefined;
     }, binding: string | undefined): Promise<string>;
+    /**
+     * In the org row lock: re-checks that the member may still use connectors and the connector
+     * exists, stores the member's tokens with the audit row; true when the connector has no tool
+     * snapshot yet (the first connection).
+     */
+    private storeTokens;
 }