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

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

package/dist/tools/oauth/flow.js

@@ -1,49 +1,33 @@
+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, randomBytes } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../../errors.js";
 import { audit } from "../../identity/audit.js";
-import { lockOrgAndAuthorize } from "../../orgs/org-lock.js";
+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 { Transactional } from "../../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER, REDIS } from "../../infra/tokens.js";
+import { OrgLock } from "../../orgs/org-lock.js";
+import { ConnectorsService } from "../connectors.service.js";
+import { Credentials } from "../credentials.js";
 import { oauthHttpOptions } from "./discovery.js";
+import { callbackUrl, DEFAULT_RETURN_PATH, OAUTH_STATE_TTL_SECONDS, publicUrlRequired, } from "./flow-paths.js";
 import { tokenRequest } from "./tokens.js";
-/** 授权回调的路径（`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";
+export { callbackUrl, DEFAULT_RETURN_PATH, isSafeReturnPath, OAUTH_BINDING_COOKIE, OAUTH_CALLBACK_PATH, OAUTH_STATE_TTL_SECONDS, publicUrlRequired, } from "./flow-paths.js";
 const stateKey = (state) => `capk:oauth-state:${state}`;
 const STATE_RE = /^[A-Za-z0-9_-]{43}$/;
 const BINDING_RE = /^[A-Za-z0-9_-]{43}$/;
 const b64url = (n = 32) => randomBytes(n).toString("base64url");
 const sha256 = (s) => createHash("sha256").update(s).digest("base64url");
-/** 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;
-    }
-}
 /** 一个有效的浏览器绑定值（复用请求里已有的，否则新生成）。 */
 export function browserBinding(existing) {
     return existing !== undefined && BINDING_RE.test(existing) ? existing : b64url();
@@ -54,13 +38,37 @@ export const FIRST_CONNECT_REFRESH_WAIT_MS = 15_000;
  * 授权码 + PKCE（S256）连接流程。state 是 32 字节随机串，存 Redis `capk:oauth-state:<state>` 10 分钟、单次有效
  * （GETDEL），内含组织、连接器、发起人、PKCE verifier、redirect_uri、回跳页面与浏览器绑定值的哈希。
  */
-export class OAuthFlow {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
+let OAuthFlow = class OAuthFlow {
+    db;
+    orgLock;
+    redis;
+    credentials;
+    config;
+    log;
+    connectors;
+    txHost;
+    constructor(db, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock, redis, credentials, config, log, 
+    /** A member's first connection without a tool snapshot refreshes the tools (A16). */
+    connectors, txHost) {
+        this.db = db;
+        this.orgLock = orgLock;
+        this.redis = redis;
+        this.credentials = credentials;
+        this.config = config;
+        this.log = log;
+        this.connectors = connectors;
+        this.txHost = txHost;
+    }
+    /** 某成员首次成功连接、而连接器还没有工具快照时（A16：用该成员的 token 刷新工具清单）。 */
+    async onFirstConnect(orgId, connectorId, accountId) {
+        await this.connectors.refresh(orgId, connectorId, accountId, undefined, {
+            trigger: "first_connect",
+        });
     }
     async app(orgId, connectorId) {
-        return this.deps.db
+        return this.db
             .selectFrom("connectors")
             .select(["id", "auth", "status"])
             .where("id", "=", connectorId)
@@ -70,7 +78,7 @@ export class OAuthFlow {
     }
     /** 生成授权 URL。`binding` 为本浏览器的绑定值（由 controller 写入 Cookie）。 */
     async start(orgId, connectorId, accountId, returnTo, binding) {
-        const publicUrl = this.deps.config().http.publicUrl;
+        const publicUrl = this.config.get().http.publicUrl;
         if (!publicUrl)
             throw publicUrlRequired();
         const app = await this.app(orgId, connectorId);
@@ -89,7 +97,7 @@ export class OAuthFlow {
                 { path: "status", message: "The connector is disabled; ask an administrator to enable it" },
             ]);
         }
-        const client = await this.deps.credentials.oauthClient(orgId, connectorId);
+        const client = await this.credentials.oauthClient(orgId, connectorId);
         if (!client?.authorizationEndpoint) {
             throw new ApiError("connector.connect_failed", "The connector has no registered OAuth client; ask an administrator to reinstall it");
         }
@@ -106,7 +114,7 @@ export class OAuthFlow {
             binding: sha256(binding),
             ...(client.issuer !== undefined && { issuer: client.issuer }),
         };
-        await this.deps.redis.set(stateKey(state), JSON.stringify(rec), "EX", OAUTH_STATE_TTL_SECONDS);
+        await this.redis.set(stateKey(state), JSON.stringify(rec), "EX", OAUTH_STATE_TTL_SECONDS);
         const url = new URL(client.authorizationEndpoint);
         url.searchParams.set("response_type", "code");
         url.searchParams.set("client_id", client.clientId);
@@ -122,7 +130,7 @@ export class OAuthFlow {
     }
     /** 回跳地址：`http.publicUrl` + 站内路径 + 结果参数（未配置 publicUrl 时为相对地址）。 */
     redirect(path, param) {
-        const base = (this.deps.config().http.publicUrl ?? "").replace(/\/+$/, "");
+        const base = (this.config.get().http.publicUrl ?? "").replace(/\/+$/, "");
         const u = new URL(path, "https://return.invalid");
         u.searchParams.set(param[0], param[1]);
         return `${base}${u.pathname}${u.search}${u.hash}`;
@@ -139,7 +147,7 @@ export class OAuthFlow {
         const state = query.state;
         if (state === undefined || !STATE_RE.test(state))
             return this.fail("state_invalid");
-        const raw = await this.deps.redis.getdel(stateKey(state));
+        const raw = await this.redis.getdel(stateKey(state));
         if (raw === null)
             return this.fail("state_invalid");
         const rec = JSON.parse(raw);
@@ -158,7 +166,7 @@ export class OAuthFlow {
             return this.fail("provider_error", back);
         const { orgId, connectorId, accountId } = rec;
         const app = await this.app(orgId, connectorId);
-        const client = app ? await this.deps.credentials.oauthClient(orgId, connectorId) : null;
+        const client = app ? await this.credentials.oauthClient(orgId, connectorId) : null;
         if (!app || !client || app.auth.type !== "oauth_code") {
             return this.fail("connector_unavailable", back);
         }
@@ -170,41 +178,15 @@ export class OAuthFlow {
                 redirect_uri: rec.redirectUri,
                 code_verifier: rec.verifier,
                 resource: client.resource,
-            }, oauthHttpOptions(this.deps.config()));
+            }, oauthHttpOptions(this.config.get()));
         }
         catch (e) {
-            this.deps.log.warn("oauth code exchange failed", { orgId, connectorId, err: e });
+            this.log.warn("oauth code exchange failed", { orgId, connectorId, err: e });
             return this.fail("token_exchange_failed", back);
         }
         let first;
         try {
-            first = await this.deps.db.transaction().execute(async (t) => {
-                await lockOrgAndAuthorize(t, orgId, accountId, "connectors.use");
-                const still = await t
-                    .selectFrom("connectors")
-                    .select("id")
-                    .where("id", "=", connectorId)
-                    .where("deleted_at", "is", null)
-                    .forUpdate()
-                    .executeTakeFirst();
-                if (!still)
-                    throw new ApiError("connector.not_found", "Connector not found");
-                await this.deps.credentials.setOAuthTokens(orgId, connectorId, { kind: "user", accountId }, tokens, t);
-                await audit(t, {
-                    actorAccountId: accountId,
-                    orgId,
-                    action: "connector.credential.set",
-                    target: connectorId,
-                    detail: { type: "oauth_code", ownership: "personal" },
-                });
-                const tool = await t
-                    .selectFrom("connector_tools")
-                    .select("name")
-                    .where("connector_id", "=", connectorId)
-                    .limit(1)
-                    .executeTakeFirst();
-                return tool === undefined;
-            });
+            first = await this.storeTokens(orgId, connectorId, accountId, tokens);
         }
         catch (e) {
             if (e instanceof ApiError)
@@ -214,10 +196,8 @@ export class OAuthFlow {
         if (first) {
             // 首次连接（A16）：刷新失败不影响连接本身，凭据已存好；管理员之后可手动刷新
             // 最多等 FIRST_CONNECT_REFRESH_WAIT_MS 再回跳（本请求自己的计时器，结束即清除）；超时的刷新在后台继续
-            const refresh = this.deps
-                .onFirstConnect(orgId, connectorId, accountId)
-                .catch((err) => {
-                this.deps.log.warn("oauth first-connect tool refresh failed", {
+            const refresh = this.onFirstConnect(orgId, connectorId, accountId).catch((err) => {
+                this.log.warn("oauth first-connect tool refresh failed", {
                     orgId,
                     connectorId,
                     err,
@@ -234,4 +214,52 @@ export class OAuthFlow {
         }
         return this.redirect(back, ["connected", connectorId]);
     }
-}
+    /**
+     * 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).
+     */
+    async storeTokens(orgId, connectorId, accountId, tokens) {
+        const t = this.db.db;
+        await this.orgLock.lockAndAuthorize(orgId, accountId, "connectors.use");
+        const still = await t
+            .selectFrom("connectors")
+            .select("id")
+            .where("id", "=", connectorId)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!still)
+            throw new ApiError("connector.not_found", "Connector not found");
+        await this.credentials.setOAuthTokens(orgId, connectorId, { kind: "user", accountId }, tokens);
+        await audit(t, {
+            actorAccountId: accountId,
+            orgId,
+            action: "connector.credential.set",
+            target: connectorId,
+            detail: { type: "oauth_code", ownership: "personal" },
+        });
+        const tool = await t
+            .selectFrom("connector_tools")
+            .select("name")
+            .where("connector_id", "=", connectorId)
+            .limit(1)
+            .executeTakeFirst();
+        return tool === undefined;
+    }
+};
+__decorate([
+    Transactional()
+], OAuthFlow.prototype, "storeTokens", null);
+OAuthFlow = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(OrgLock)),
+    __param(2, Inject(REDIS)),
+    __param(3, Inject(Credentials)),
+    __param(4, Inject(KernelConfigService)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(ConnectorsService)),
+    __param(7, Inject(TransactionHost))
+], OAuthFlow);
+export { OAuthFlow };

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

@@ -1,9 +1,9 @@
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
-import type { KernelConfig } from "../../config/schema.js";
 import { type Principal } from "../../identity/principal.js";
+import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import { type OrgContext } from "../../orgs/org.guard.js";
-import { type OAuthFlow } from "./flow.js";
+import { OAuthFlow } from "./flow.js";
 declare const ConnectBody: z.ZodObject<{
     returnTo: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -14,7 +14,7 @@ declare const ConnectBody: z.ZodObject<{
 export declare class OAuthConnectController {
     private readonly flow;
     private readonly config;
-    constructor(flow: OAuthFlow, config: () => KernelConfig);
+    constructor(flow: OAuthFlow, config: KernelConfigService);
     connect(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof ConnectBody>, req: FastifyRequest, reply: FastifyReply): Promise<{
         authorizationUrl: string;
     }>;

package/dist/tools/oauth/oauth.controller.js

@@ -7,13 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Get, HttpCode, Inject, Param, Post, Query, Req, Res, } from "@nestjs/common";
+import { Controller, Get, HttpCode, Inject, Param, Post, Query, Req, Res } from "@nestjs/common";
 import { z } from "zod";
-import { KERNEL_CONFIG, OAUTH_FLOW } from "../../http/tokens.js";
-import { ZodPipe } from "../../http/zod.pipe.js";
 import { CurrentPrincipal, Public, requireUser } from "../../identity/principal.js";
+import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
+import { createZodDto } from "../../infra/validation/create-zod-dto.js";
+import { ZBody } from "../../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../../orgs/org.guard.js";
-import { browserBinding, isSafeReturnPath, OAUTH_BINDING_COOKIE, OAUTH_CALLBACK_PATH, OAUTH_STATE_TTL_SECONDS, } from "./flow.js";
+import { browserBinding, isSafeReturnPath, OAUTH_BINDING_COOKIE, OAUTH_CALLBACK_PATH, OAUTH_STATE_TTL_SECONDS, OAuthFlow, } from "./flow.js";
 const ConnectBody = z
     .object({
     returnTo: z
@@ -23,6 +24,8 @@ const ConnectBody = z
         .optional(),
 })
     .strict();
+class OAuthConnectBody extends createZodDto(ConnectBody, "OAuthConnectBody") {
+}
 /** 查询参数只取单值字符串（重复参数 / 数组按缺失处理）。 */
 const one = (v) => typeof v === "string" && v.length <= 4096 ? v : undefined;
 /**
@@ -44,7 +47,7 @@ let OAuthConnectController = class OAuthConnectController {
             path: OAUTH_CALLBACK_PATH,
             httpOnly: true,
             sameSite: "lax",
-            secure: this.config().auth.cookieSecure,
+            secure: this.config.get().auth.cookieSecure,
             maxAge: OAUTH_STATE_TTL_SECONDS,
         });
         return out;
@@ -57,14 +60,14 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("connectorId")),
-    __param(3, Body(new ZodPipe(ConnectBody))),
+    __param(3, ZBody(OAuthConnectBody)),
     __param(4, Req()),
     __param(5, Res({ passthrough: true }))
 ], OAuthConnectController.prototype, "connect", null);
 OAuthConnectController = __decorate([
     Controller("api/v1/orgs/:orgId/connectors"),
-    __param(0, Inject(OAUTH_FLOW)),
-    __param(1, Inject(KERNEL_CONFIG))
+    __param(0, Inject(OAuthFlow)),
+    __param(1, Inject(KernelConfigService))
 ], OAuthConnectController);
 export { OAuthConnectController };
 /**
@@ -90,6 +93,6 @@ __decorate([
 ], OAuthCallbackController.prototype, "callback", null);
 OAuthCallbackController = __decorate([
     Controller("api/v1/oauth"),
-    __param(0, Inject(OAUTH_FLOW))
+    __param(0, Inject(OAuthFlow))
 ], OAuthCallbackController);
 export { OAuthCallbackController };

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

@@ -1,6 +1,7 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
+import type { LockService } from "../../infra/lock/lock.service.js";
 import { type OAuthHttpOptions } from "./discovery.js";
 export type TokenAuthMethod = "client_secret_basic" | "client_secret_post" | "none";
 /**
@@ -83,17 +84,24 @@ export type TokenAuth = {
  *
  * - 调用前：未过期（距过期 > 60 秒或未告知过期时间）直接用；否则刷新（授权码流用 refresh token，客户端凭据流重新取）。
  * - 收到 401：`forceRefresh(stale)`——只要库里的 token 仍是收到 401 的那个就刷新。
- * - 刷新一律在 Redis 锁 `capk:oauth-refresh:<orgId>:<connectorId>:<owner>` 内进行（SET NX PX，值为本次随机 id，
- *   只删除自己持有的锁）；拿不到锁的轮询等锁消失后重读凭据，库里已是别的 token 就直接用（不并发刷新——授权服务器
+ * - 刷新一律在 Redis 锁 `capk:oauth-refresh:<orgId>:<connectorId>:<owner>` 内进行（`LockService.lease`，值为
+ *   本次随机 id，`releaseIf` 只删除自己持有的锁）；拿不到锁的轮询等锁消失后重读凭据，库里已是别的 token 就直接用（不并发刷新——授权服务器
  *   轮换 refresh token 时，并发刷新的第二个必然失败）。
  * - 令牌端点明确拒绝 → 删除该凭据并抛 OAuthReconnectRequired（需要重新连接）；暂时不可用 → OAuthUnavailable，凭据保留。
  */
 export declare class OAuthTokens {
     private readonly store;
+    /** The lease primitives of `LockService` (the key is used as is: no `lock:` prefix). */
+    private readonly locks;
+    /** Polls whether another holder still has the lock. */
     private readonly redis;
     private readonly http;
     private readonly log;
-    constructor(store: OAuthStore, redis: Redis, http: () => OAuthHttpOptions, log: Logger);
+    constructor(store: OAuthStore, 
+    /** The lease primitives of `LockService` (the key is used as is: no `lock:` prefix). */
+    locks: Pick<LockService, "lease" | "releaseIf" | "renew">, 
+    /** Polls whether another holder still has the lock. */
+    redis: Pick<Redis, "exists">, http: () => OAuthHttpOptions, log: Logger);
     accessToken(orgId: string, connectorId: string, auth: TokenAuth, owner: OAuthOwner): Promise<string>;
     /** 收到 401 后调用：`stale` 为收到 401 的那个 access token。 */
     forceRefresh(orgId: string, connectorId: string, auth: TokenAuth, owner: OAuthOwner, stale: string | undefined): Promise<void>;

package/dist/tools/oauth/tokens.js

@@ -102,30 +102,30 @@ export async function tokenRequest(client, params, http) {
         ...(typeof scope === "string" && { scope }),
     };
 }
-const RELEASE = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('DEL', KEYS[1])
-end
-return 0
-`;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * access token 的获取与刷新。
  *
  * - 调用前：未过期（距过期 > 60 秒或未告知过期时间）直接用；否则刷新（授权码流用 refresh token，客户端凭据流重新取）。
  * - 收到 401：`forceRefresh(stale)`——只要库里的 token 仍是收到 401 的那个就刷新。
- * - 刷新一律在 Redis 锁 `capk:oauth-refresh:<orgId>:<connectorId>:<owner>` 内进行（SET NX PX，值为本次随机 id，
- *   只删除自己持有的锁）；拿不到锁的轮询等锁消失后重读凭据，库里已是别的 token 就直接用（不并发刷新——授权服务器
+ * - 刷新一律在 Redis 锁 `capk:oauth-refresh:<orgId>:<connectorId>:<owner>` 内进行（`LockService.lease`，值为
+ *   本次随机 id，`releaseIf` 只删除自己持有的锁）；拿不到锁的轮询等锁消失后重读凭据，库里已是别的 token 就直接用（不并发刷新——授权服务器
  *   轮换 refresh token 时，并发刷新的第二个必然失败）。
  * - 令牌端点明确拒绝 → 删除该凭据并抛 OAuthReconnectRequired（需要重新连接）；暂时不可用 → OAuthUnavailable，凭据保留。
  */
 export class OAuthTokens {
     store;
+    locks;
     redis;
     http;
     log;
-    constructor(store, redis, http, log) {
+    constructor(store, 
+    /** The lease primitives of `LockService` (the key is used as is: no `lock:` prefix). */
+    locks, 
+    /** Polls whether another holder still has the lock. */
+    redis, http, log) {
         this.store = store;
+        this.locks = locks;
         this.redis = redis;
         this.http = http;
         this.log = log;
@@ -165,7 +165,7 @@ export class OAuthTokens {
         const replaced = (rec) => rec !== null && rec.access_token !== stale ? rec.access_token : undefined;
         for (;;) {
             const id = randomUUID();
-            if ((await this.redis.set(key, id, "PX", ttlMs, "NX")) === "OK") {
+            if (await this.locks.lease(key, id, ttlMs)) {
                 try {
                     const rec = await this.store.readTokens(orgId, connectorId, owner);
                     const done = replaced(rec);
@@ -173,10 +173,10 @@ export class OAuthTokens {
                         return done;
                     if (rec === null && auth.type === "oauth_code")
                         throw new OAuthReconnectRequired(owner);
-                    return await this.obtain(orgId, connectorId, auth, owner, rec, key, id);
+                    return await this.obtain(orgId, connectorId, auth, owner, rec, key, id, ttlMs);
                 }
                 finally {
-                    await this.redis.eval(RELEASE, 1, key, id).catch((err) => {
+                    await this.locks.releaseIf(key, id).catch((err) => {
                         this.log.warn("oauth refresh lock release failed", { connectorId, err });
                     });
                 }
@@ -198,7 +198,7 @@ export class OAuthTokens {
      * 锁内：向令牌端点要新 token 并写回。作废前做围栏检查：锁仍归自己、库里的 token 仍是这次用掉的那组——
      * 锁过期后另一个刷新者若已写入新 token，就直接用它而不是删掉它。
      */
-    async obtain(orgId, connectorId, auth, owner, rec, lockKey, lockId) {
+    async obtain(orgId, connectorId, auth, owner, rec, lockKey, lockId, lockTtlMs) {
         const client = await this.store.readClient(orgId, connectorId);
         if (!client)
             throw new OAuthReconnectRequired({ kind: "org" });
@@ -210,7 +210,8 @@ export class OAuthTokens {
                 current.refresh_token === rec.refresh_token;
             if (current !== null && !unchanged)
                 return current.access_token;
-            if (current !== null && (await this.redis.get(lockKey)) !== lockId) {
+            // still ours (renewing a held lease is harmless right before the delete)
+            if (current !== null && !(await this.locks.renew(lockKey, lockId, lockTtlMs))) {
                 // 锁已不归自己（过期）：不删，交给持锁者；这次按暂时不可用处理
                 throw new OAuthUnavailable();
             }

package/dist/tools/outputs.d.ts

@@ -1,5 +1,6 @@
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 /** 文本行数（按 `\n` 切分；空串算 1 行，与按行分页读取一致）。 */
 export declare function countLines(s: string): number;
 export interface SavedOutput {
@@ -14,12 +15,13 @@ export interface OutputScope {
 }
 /**
  * 输出存档（spec 5.4）：超大工具结果的全文存进 `capybara.tool_outputs`，保留 `tools.outputRetentionDays` 天。
- * 只能在产生它的会话里读取（同组织别的会话也不行：会话之间可见范围不同），过期即视为不存在（清理由维护任务负责）。
+ * 只能在产生它的会话里读取（同组织别的会话也不行：会话之间可见范围不同），过期即视为不存在（清理由
+ * `output-cleanup` 每小时一次，见 {@link deleteExpiredOutputs}）。
  */
 export declare class ToolOutputs {
     private readonly db;
     private readonly config;
-    constructor(db: KernelDb, config: () => KernelConfig);
+    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">);
     save(a: {
         orgId: string;
         conversationId: string;
@@ -29,6 +31,13 @@ export declare class ToolOutputs {
     /** 读本会话未过期的存档全文；不存在 / 过期 / 属于别的会话或组织 → null。 */
     load(scope: OutputScope, id: string): Promise<string | null>;
 }
+/** Rows deleted per statement by {@link deleteExpiredOutputs}. */
+export declare const OUTPUT_CLEANUP_BATCH = 1000;
+/**
+ * 删除已过期（`expires_at < now()`）的输出存档，每批 `batch` 行，直到删完；返回删除的总行数。
+ * 每批一条独立语句（不开长事务）；多个 worker 同时清理时 `SKIP LOCKED` 互不等待。
+ */
+export declare function deleteExpiredOutputs(db: KernelSchemaDb, batch?: number): Promise<number>;
 /** 存档不存在 / 过期 / 不属于本会话（模型可见，英文；不区分几种情况，不泄露别处的存档是否存在）。 */
 export declare const outputNotFoundText: (id: string) => string;
 /**