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

package/dist/tools/drift.js

@@ -1,12 +1,29 @@
+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 { TOOL_TITLE_MAX, ToolError, validateToolPresentation, } from "@capybara-hq/plugin-sdk";
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.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 } from "../infra/tokens.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { HIDDEN_FORMAT_RE } from "../text.js";
-import { CredentialMissing, isOAuth } from "./credentials.js";
+import { CredentialMissing, Credentials, isOAuth } from "./credentials.js";
 import { toolKey, toolKeyIssue } from "./naming.js";
 import { redactDeep, redactorFor } from "./redact.js";
-import { canonicalJson, policyFromAnnotations, specHash } from "./registry.js";
+import { canonicalJson, policyFromAnnotations, specHash, ToolRegistry } from "./registry.js";
 import { resourceToolSpecs } from "./resources.js";
 import { recordToolSpecs } from "./specs.js";
 /**
@@ -20,15 +37,12 @@ import { recordToolSpecs } from "./specs.js";
  * 连接器从未拍过快照（`tools_synced_at` 为空且没有工具行，即 OAuth 授权码连接器安装时不 listTools，A16）时，
  * 首个快照按安装处理（直接启用）。
  *
- * 触发：维护队列的周期扫描（`tools.driftIntervalHours`）、连接器在会话中报告工具清单变了（MCP
+ * 触发：周期扫描（`drift-scan`，每 `tools.driftIntervalHours` 一次的 `@LockedInterval`，见 jobs.ts）、连接器在会话中报告工具清单变了（MCP
  * `notifications/tools/list_changed`）、管理员手动刷新（`ConnectorsService.refresh`，走同一套比对）。
  * 授权（`tool_grants` / `conversation_tool_grants`）按 spec_hash 比对（D8），复核通过采用新指纹后旧授权自然失效。
  */
-/** 周期扫描：任务名与 job scheduler id（不含 `:`）。 */
-export const DRIFT_SCAN_JOB = "drift-scan";
-export const DRIFT_SCHEDULER_ID = "drift-scan-interval";
-/** 单个连接器的漂移检查任务名。 */
-export const DRIFT_CONNECTOR_JOB = "drift-connector";
+import { DRIFT_CONNECTOR_JOB } from "./job-ids.js";
+export { DRIFT_CONNECTOR_JOB, DRIFT_SCAN_JOB, DRIFT_SCHEDULER_ID } from "./job-ids.js";
 /**
  * list_changed 触发的检查：jobId 按连接器与分钟桶去重（同一分钟内多次通知只检查一次；connectorId 为 UUID，不含 `:`）。
  */
@@ -167,30 +181,28 @@ export function toolIssue(slug, spec) {
 }
 /** 任务保留时长：完成的 jobId 留一段时间，同一桶内的重复投递被 BullMQ 按 jobId 去重。 */
 const KEEP_FAILED = { age: 86_400 };
-export class ToolDrift {
-    d;
-    constructor(d) {
-        this.d = d;
-        const m = d.maintenance;
-        if (m) {
-            m.schedule({
-                id: DRIFT_SCHEDULER_ID,
-                name: DRIFT_SCAN_JOB,
-                everyMs: () => this.intervalMs(),
-            });
-            m.handle(DRIFT_SCAN_JOB, async () => {
-                const n = await this.scan();
-                if (n > 0)
-                    d.log.info("tool drift checks enqueued", { count: n });
-            });
-            m.handle(DRIFT_CONNECTOR_JOB, async (job) => {
-                const { orgId, connectorId, trigger } = job.data;
-                await this.check(orgId, connectorId, trigger);
-            });
-        }
+let ToolDrift = class ToolDrift {
+    db;
+    registry;
+    credentials;
+    config;
+    log;
+    queue;
+    txHost;
+    constructor(db, registry, credentials, config, log, 
+    /** The maintenance queue's producer (`drift-connector` jobs). */
+    queue, txHost) {
+        this.db = db;
+        this.registry = registry;
+        this.credentials = credentials;
+        this.config = config;
+        this.log = log;
+        this.queue = queue;
+        this.txHost = txHost;
     }
+    /** The scan period (`tools.driftIntervalHours`). */
     intervalMs() {
-        return this.d.config().tools.driftIntervalHours * 3_600_000;
+        return this.config.get().tools.driftIntervalHours * 3_600_000;
     }
     /**
      * 打开一次会话拉工具清单，无论成败都关闭会话；会话带 `listResources` 即视为支持 resources。
@@ -200,11 +212,11 @@ export class ToolDrift {
     async listTools(connector, endpoint, auth, logCtx, 
     /** 收到 401：OAuth 连接器在刷新锁内刷新（参数为最后一次注入的鉴权）。 */
     onUnauthorized = async () => { }) {
-        const c = this.d.registry.findConnector(connector);
+        const c = this.registry.findConnector(connector);
         if (!c) {
             throw new ApiError("connector.connect_failed", `The connector ${connector} is not installed`);
         }
-        const signal = AbortSignal.timeout(this.d.config().tools.timeoutMs);
+        const signal = AbortSignal.timeout(this.config.get().tools.timeoutMs);
         const injected = [];
         const tracked = async () => {
             const inj = await auth();
@@ -230,20 +242,21 @@ export class ToolDrift {
             if (e instanceof CredentialMissing)
                 throw e;
             // 日志经 logger 打码（凭据值已在构造注入时登记）
-            this.d.log.warn("connector listTools failed", { ...logCtx, connector, err: e });
+            this.log.warn("connector listTools failed", { ...logCtx, connector, err: e });
             throw new ApiError("connector.connect_failed", connectFailedMessage(e, redactorFor(injected)));
         }
         finally {
             await session?.close().catch((e) => {
-                this.d.log.warn("connector session close failed", { ...logCtx, connector, err: e });
+                this.log.warn("connector session close failed", { ...logCtx, connector, err: e });
             });
         }
     }
     /**
-     * 把新快照与当前工具行比对并写入（调用方已在事务内锁住连接器行）；返回按名排序的变化。
+     * 把新快照与当前工具行比对并写入（调用方已在事务内锁住连接器行：`mandatory`）；返回按名排序的变化。
      * 规则见文件头。待复核的新定义也写进 `tool_specs`（内容寻址，只增不改）。
      */
-    async apply(t, app, rows) {
+    async apply(app, rows) {
+        const t = this.db.db;
         const current = await t
             .selectFrom("connector_tools")
             .select([
@@ -341,7 +354,7 @@ export class ToolDrift {
                             .where("name", "=", r.name)
                             .execute();
                         // No audit row (the model sees nothing new), but leave a trace for operators.
-                        this.d.log.info("connector tool display updated", {
+                        this.log.info("connector tool display updated", {
                             event: "connector.tool_display_updated",
                             connectorId: app.id,
                             tool: r.name,
@@ -393,8 +406,8 @@ export class ToolDrift {
      * 连不上 / 都失败 → 跳过（不改快照，下个周期或下次通知再查）。
      */
     async check(orgId, connectorId, trigger) {
-        const { db, log } = this.d;
-        const app = (await db
+        const log = this.log;
+        const app = (await this.db
             .selectFrom("connectors")
             .select([
             "id",
@@ -415,7 +428,7 @@ export class ToolDrift {
             return { status: "skipped", reason: "not_found" };
         if (app.status !== "active")
             return { status: "skipped", reason: "inactive" };
-        if (!this.d.registry.findConnector(app.connector)) {
+        if (!this.registry.findConnector(app.connector)) {
             log.warn("tool drift check skipped: connector not installed", {
                 orgId,
                 connectorId,
@@ -427,7 +440,7 @@ export class ToolDrift {
         const personal = auth.type !== "none" && !isOAuth(auth) && auth.ownership === "personal";
         const personalOAuth = auth.type === "oauth_code";
         const accounts = personal || personalOAuth
-            ? await this.d.credentials.personalHolders(orgId, connectorId, PERSONAL_CANDIDATES)
+            ? await this.credentials.personalHolders(orgId, connectorId, PERSONAL_CANDIDATES)
             : [app.created_by];
         if (accounts.length === 0) {
             log.info("tool drift check skipped: no member credential", { orgId, connectorId });
@@ -437,7 +450,7 @@ export class ToolDrift {
         let reason = "no_credential";
         for (const accountId of accounts) {
             try {
-                listed = await this.listTools(app.connector, app.endpoint, () => this.d.credentials.injection(orgId, connectorId, auth, accountId), { orgId, connectorId, trigger }, (last) => this.d.credentials.onUnauthorized(orgId, connectorId, auth, accountId, last));
+                listed = await this.listTools(app.connector, app.endpoint, () => this.credentials.injection(orgId, connectorId, auth, accountId), { orgId, connectorId, trigger }, (last) => this.credentials.onUnauthorized(orgId, connectorId, auth, accountId, last));
                 break;
             }
             catch (e) {
@@ -455,53 +468,57 @@ export class ToolDrift {
             return { status: "skipped", reason };
         }
         const { rows } = snapshot(app.slug, listed.specs, listed.resources);
-        const changes = await db.transaction().execute(async (t) => {
-            const locked = await t
-                .selectFrom("connectors")
-                .select(["id", "tools_synced_at"])
-                .where("id", "=", connectorId)
-                .where("deleted_at", "is", null)
-                .where("status", "=", "active")
-                .forUpdate()
-                .executeTakeFirst();
-            if (!locked)
-                return null;
-            const c = await this.apply(t, locked, rows);
-            if (c.added.length + c.changed.length + c.removed.length > 0) {
-                await audit(t, {
-                    orgId,
-                    action: "connector.tools_drifted",
-                    target: connectorId,
-                    detail: {
-                        added: c.added.length,
-                        changed: c.changed.length,
-                        removed: c.removed.length,
-                        trigger,
-                    },
-                });
-            }
-            return c;
-        });
+        const changes = await this.applyChecked(orgId, connectorId, trigger, rows);
         if (!changes)
             return { status: "skipped", reason: "inactive" };
         return { status: "checked", changes };
     }
+    /** The locked compare-and-write of {@link check}, audited when something changed. */
+    async applyChecked(orgId, connectorId, trigger, rows) {
+        const t = this.db.db;
+        const locked = await t
+            .selectFrom("connectors")
+            .select(["id", "tools_synced_at"])
+            .where("id", "=", connectorId)
+            .where("deleted_at", "is", null)
+            .where("status", "=", "active")
+            .forUpdate()
+            .executeTakeFirst();
+        if (!locked)
+            return null;
+        const c = await this.apply(locked, rows);
+        if (c.added.length + c.changed.length + c.removed.length > 0) {
+            await audit(t, {
+                orgId,
+                action: "connector.tools_drifted",
+                target: connectorId,
+                detail: {
+                    added: c.added.length,
+                    changed: c.changed.length,
+                    removed: c.removed.length,
+                    trigger,
+                },
+            });
+        }
+        return c;
+    }
     /**
      * 连接器在会话中报告工具清单变了：投递一次该连接器的检查（jobId 按分钟桶去重）。投递失败只记日志。
      */
     async onToolsChanged(orgId, connectorId) {
-        const m = this.d.maintenance;
-        if (!m || connectorId.includes(":"))
+        if (connectorId.includes(":"))
             return;
         try {
-            await m.add(DRIFT_CONNECTOR_JOB, { orgId, connectorId, trigger: "list_changed" }, {
+            await this.queue.add(DRIFT_CONNECTOR_JOB, { orgId, connectorId, trigger: "list_changed" }, {
                 jobId: listChangedJobId(connectorId),
+                // a check runs once: a failure waits for the next trigger (the queue default retries)
+                attempts: 1,
                 removeOnComplete: { age: 3_600 },
                 removeOnFail: KEEP_FAILED,
             });
         }
         catch (err) {
-            this.d.log.warn("cannot enqueue tool drift check", { orgId, connectorId, err });
+            this.log.warn("cannot enqueue tool drift check", { orgId, connectorId, err });
         }
     }
     /**
@@ -509,12 +526,9 @@ export class ToolDrift {
      * jobId 按周期桶去重——即使扫描在多个副本上重复执行，每个连接器每周期也只检查一次。返回投递数。
      */
     async scan() {
-        const m = this.d.maintenance;
-        if (!m)
-            return 0;
         const interval = this.intervalMs();
         const bucket = Math.floor(Date.now() / interval);
-        const apps = await this.d.db
+        const apps = await this.db
             .selectFrom("connectors")
             .select(["id", "org_id"])
             .where("deleted_at", "is", null)
@@ -528,12 +542,30 @@ export class ToolDrift {
         for (const a of apps) {
             if (a.id.includes(":"))
                 continue;
-            await m.add(DRIFT_CONNECTOR_JOB, { orgId: a.org_id, connectorId: a.id, trigger: "schedule" }, {
+            await this.queue.add(DRIFT_CONNECTOR_JOB, { orgId: a.org_id, connectorId: a.id, trigger: "schedule" }, {
                 jobId: driftScanJobId(a.id, bucket),
+                attempts: 1,
                 removeOnComplete: { age: Math.ceil(interval / 1000) },
                 removeOnFail: KEEP_FAILED,
             });
         }
         return apps.length;
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ToolDrift.prototype, "apply", null);
+__decorate([
+    Transactional()
+], ToolDrift.prototype, "applyChecked", null);
+ToolDrift = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ToolRegistry)),
+    __param(2, Inject(Credentials)),
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(KERNEL_LOGGER)),
+    __param(5, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(6, Inject(TransactionHost))
+], ToolDrift);
+export { ToolDrift };

package/dist/tools/info.d.ts

@@ -1,5 +1,7 @@
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { ToolRegistry } from "./registry.js";
+import { ConversationAccess } from "../conversations/access.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ToolRegistry } from "./registry.js";
 /**
  * Tool presentation metadata for the conversation page (UI refresh B, design spec §6.16.9): the
  * kind picks the row verb and the group counts, the title and key arguments the row's wording.
@@ -35,7 +37,7 @@ export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
 export declare const TOOL_INFO_MAX_KEYS = 100;
 export declare const TOOL_INFO_KEY_MAX = 200;
 export interface ToolInfoDeps {
-    db: KernelDb;
+    db: KernelSchemaDb;
     registry: Pick<ToolRegistry, "builtinSpecs" | "extensionToolSpecs">;
 }
 /**
@@ -55,13 +57,14 @@ export interface ToolInfoDeps {
  *   here it only changes the label.
  */
 export declare function toolInfo(deps: ToolInfoDeps, orgId: string, keys: readonly string[]): Promise<ToolInfo[]>;
-export interface ConversationToolInfoDeps extends ToolInfoDeps {
-    /** Conversation visibility (the same rule as the events API: `ConversationsService.isAccessible`). */
-    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
-}
 /** `GET /conversations/:id/tools`: {@link toolInfo} for a conversation the viewer can read. */
 export declare class ConversationToolInfo {
-    private readonly d;
-    constructor(d: ConversationToolInfoDeps);
+    private readonly db;
+    private readonly registry;
+    /** Conversation visibility (the same rule as the events API). */
+    private readonly access;
+    constructor(db: KernelDb, registry: Pick<ToolRegistry, "builtinSpecs" | "extensionToolSpecs">, 
+    /** Conversation visibility (the same rule as the events API). */
+    access: Pick<ConversationAccess, "isAccessible">);
     get(orgId: string, conversationId: string, viewerAccountId: string, keys: readonly string[]): Promise<ToolInfo[]>;
 }

package/dist/tools/info.js

@@ -1,6 +1,19 @@
+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 { ConversationAccess } from "../conversations/access.js";
 import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 import { UUID_RE } from "../ui/registry.js";
 import { KEY_SEPARATOR, toolKey } from "./naming.js";
+import { ToolRegistry } from "./registry.js";
 /** Kinds of the kernel builtin tools; a builtin missing here is a plain `tool`. */
 export const BUILTIN_TOOL_KINDS = {
     sandbox_bash: "command",
@@ -98,16 +111,29 @@ export async function toolInfo(deps, orgId, keys) {
     });
 }
 /** `GET /conversations/:id/tools`: {@link toolInfo} for a conversation the viewer can read. */
-export class ConversationToolInfo {
-    d;
-    constructor(d) {
-        this.d = d;
+let ConversationToolInfo = class ConversationToolInfo {
+    db;
+    registry;
+    access;
+    constructor(db, registry, 
+    /** Conversation visibility (the same rule as the events API). */
+    access) {
+        this.db = db;
+        this.registry = registry;
+        this.access = access;
     }
     async get(orgId, conversationId, viewerAccountId, keys) {
         if (!UUID_RE.test(conversationId) ||
-            !(await this.d.isAccessible(orgId, conversationId, viewerAccountId))) {
+            !(await this.access.isAccessible(orgId, conversationId, viewerAccountId))) {
             throw new ApiError("conversation.not_found", "Conversation not found");
         }
-        return toolInfo(this.d, orgId, keys);
+        return toolInfo({ db: this.db.db, registry: this.registry }, orgId, keys);
     }
-}
+};
+ConversationToolInfo = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ToolRegistry)),
+    __param(2, Inject(ConversationAccess))
+], ConversationToolInfo);
+export { ConversationToolInfo };

package/dist/tools/job-ids.d.ts

@@ -0,0 +1,13 @@
+/** The periodic drift scan (`@LockedInterval`, tools/jobs.ts). */
+export declare const DRIFT_SCAN_JOB = "drift-scan";
+/** The BullMQ repeatable scheduler the scan had before it became `@LockedInterval` (retired). */
+export declare const DRIFT_SCHEDULER_ID = "drift-scan-interval";
+/**
+ * 单个连接器的漂移检查任务名（维护队列上的一次性任务：生产方是 `ToolDrift`，消费方是
+ * `MaintenanceProcessor`）。
+ */
+export declare const DRIFT_CONNECTOR_JOB = "drift-connector";
+/** The hourly cleanup of expired tool output archives (`@LockedCron`, tools/jobs.ts). */
+export declare const OUTPUT_CLEANUP_JOB = "output-cleanup";
+/** The BullMQ repeatable scheduler the cleanup had before it became `@LockedCron` (retired). */
+export declare const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";

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