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

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";
 /**
@@ -40,13 +41,24 @@ export type OAuthOwner = {
     kind: "user";
     accountId: string;
 };
-/** 令牌端点以 400 / 401 + RFC 6749 错误码明确拒绝（如 `invalid_grant`）。 */
+/**
+ * The token endpoint refused with an RFC 6749-shaped error code (`invalid_grant`, ...): a 400 / 401
+ * with `error`, or a 200 whose body carries `ok: false` (Slack) or an `error` and no token.
+ */
 export declare class OAuthGrantError extends Error {
     readonly error: string;
     constructor(error: string);
 }
-/** 这些错误码说明凭据本身已失效（refresh token / 客户端），只有它们才作废令牌。 */
+/**
+ * These codes say the credential itself is dead (refresh token / client); only they invalidate the
+ * tokens. Besides RFC 6749's, Slack's `invalid_refresh_token`, `token_revoked` and `token_expired`.
+ */
 export declare const INVALIDATING_ERRORS: ReadonlySet<string>;
+/**
+ * `token_type` values (lower case) stored and sent as `Authorization: Bearer`: RFC 6750 `Bearer`
+ * and Slack's `user` (`oauth.v2.user.access`). A template may allow more with `auth.tokenTypes`.
+ */
+export declare const BEARER_TOKEN_TYPES: ReadonlySet<string>;
 /** 授权服务器暂时不可用（网络、超时、5xx、畸形响应）：模型可见的英文说明，计入「服务不可用」。 */
 export declare class OAuthUnavailable extends ToolError {
     constructor(message?: string);
@@ -58,12 +70,26 @@ export declare class OAuthReconnectRequired extends Error {
 }
 /** access token 过期前多久就刷新。 */
 export declare const REFRESH_MARGIN_MS = 60000;
+/** What the connector's auth settings add to a token request. */
+export interface TokenRequestOptions {
+    /** More `token_type` values to accept as bearer tokens (`auth.tokenTypes`, case-insensitive). */
+    tokenTypes?: readonly string[] | undefined;
+}
 /**
- * 调令牌端点（RFC 6749 §3.2）：按客户端认证方式带 client_id / secret（Basic 按 §2.3.1 先表单编码）。
- * 400 / 401 且正文带可解析的 RFC 6749 `error` 码 → OAuthGrantError；其余（网络错误、超时、429、408、
- * 403 等其他 4xx、没有错误码的 4xx、5xx、3xx、畸形响应）→ OAuthUnavailable——网关限流或 WAF 拦截不能当成凭据失效。
+ * Calls the token endpoint (RFC 6749 §3.2), sending client_id / secret per the client's auth method
+ * (Basic form-encodes them first, §2.3.1).
+ * - 400 / 401 with a parsable RFC 6749 `error` code -> OAuthGrantError.
+ * - 200 with `ok: false` (Slack reports every error this way), or with an `error` code and no
+ *   `access_token` -> OAuthGrantError with that code (`ok: false` wins over an `access_token`); a
+ *   transient code (`temporarily_unavailable`, `server_error`, Slack's `ratelimited`, ...) or no
+ *   parsable code -> OAuthUnavailable.
+ * - Everything else (network error, timeout, 429, 408, 403 and other 4xx, a 4xx without a code,
+ *   5xx, 3xx, a malformed body) -> OAuthUnavailable: a gateway's rate limit or a WAF block is not a
+ *   dead credential.
+ * - A `token_type` other than Bearer / `user` / `opts.tokenTypes` -> OAuthGrantError
+ *   `unsupported_token_type`; an accepted one is stored as `Bearer`.
  */
-export declare function tokenRequest(client: OAuthClientRecord, params: Record<string, string | undefined>, http: OAuthHttpOptions): Promise<OAuthTokenRecord>;
+export declare function tokenRequest(client: OAuthClientRecord, params: Record<string, string | undefined>, http: OAuthHttpOptions, opts?: TokenRequestOptions): Promise<OAuthTokenRecord>;
 /** 令牌与客户端的存取（由 Credentials 实现：信封加密存入 capybara.secrets）。 */
 export interface OAuthStore {
     readClient(orgId: string, connectorId: string): Promise<OAuthClientRecord | null>;
@@ -72,28 +98,37 @@ export interface OAuthStore {
     deleteTokens(orgId: string, connectorId: string, owner: OAuthOwner): Promise<void>;
 }
 /** 取 token 所需的认证方式字段（与 credentials.ts 的 OAuthAuth 对应）。 */
-export type TokenAuth = {
+export type TokenAuth = ({
     type: "oauth_code";
 } | {
     type: "oauth_client";
     scopes?: string[] | undefined;
+}) & {
+    tokenTypes?: string[] | undefined;
 };
 /**
  * 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 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

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { OAuthSetupError, oauthFetch } from "./discovery.js";
-/** 令牌端点以 400 / 401 + RFC 6749 错误码明确拒绝（如 `invalid_grant`）。 */
+/**
+ * The token endpoint refused with an RFC 6749-shaped error code (`invalid_grant`, ...): a 400 / 401
+ * with `error`, or a 200 whose body carries `ok: false` (Slack) or an `error` and no token.
+ */
 export class OAuthGrantError extends Error {
     error;
     constructor(error) {
@@ -10,12 +13,37 @@ export class OAuthGrantError extends Error {
         this.name = "OAuthGrantError";
     }
 }
-/** 这些错误码说明凭据本身已失效（refresh token / 客户端），只有它们才作废令牌。 */
+/**
+ * These codes say the credential itself is dead (refresh token / client); only they invalidate the
+ * tokens. Besides RFC 6749's, Slack's `invalid_refresh_token`, `token_revoked` and `token_expired`.
+ */
 export const INVALIDATING_ERRORS = new Set([
     "invalid_grant",
     "invalid_client",
     "unauthorized_client",
+    "invalid_refresh_token",
+    "token_revoked",
+    "token_expired",
+]);
+/**
+ * Error codes of a 200 error body that mean "try again later", not a refusal: they count as
+ * unavailable like a 429 / 5xx. RFC 6749's `temporarily_unavailable` / `server_error` and Slack's
+ * Web API codes.
+ */
+const TRANSIENT_ERRORS = new Set([
+    "temporarily_unavailable",
+    "server_error",
+    "ratelimited",
+    "service_unavailable",
+    "internal_error",
+    "fatal_error",
+    "request_timeout",
 ]);
+/**
+ * `token_type` values (lower case) stored and sent as `Authorization: Bearer`: RFC 6750 `Bearer`
+ * and Slack's `user` (`oauth.v2.user.access`). A template may allow more with `auth.tokenTypes`.
+ */
+export const BEARER_TOKEN_TYPES = new Set(["bearer", "user"]);
 /** 授权服务器暂时不可用（网络、超时、5xx、畸形响应）：模型可见的英文说明，计入「服务不可用」。 */
 export class OAuthUnavailable extends ToolError {
     constructor(message = "Could not obtain an access token: the app's authorization server is unavailable. Try again later.") {
@@ -40,11 +68,20 @@ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** RFC 6749 §5.2 形式的错误码（只有这种串才写进日志 / 错误，不回显对方任意文本）。 */
 const OAUTH_ERROR_RE = /^[a-z][a-z0-9_]{0,63}$/;
 /**
- * 调令牌端点（RFC 6749 §3.2）：按客户端认证方式带 client_id / secret（Basic 按 §2.3.1 先表单编码）。
- * 400 / 401 且正文带可解析的 RFC 6749 `error` 码 → OAuthGrantError；其余（网络错误、超时、429、408、
- * 403 等其他 4xx、没有错误码的 4xx、5xx、3xx、畸形响应）→ OAuthUnavailable——网关限流或 WAF 拦截不能当成凭据失效。
+ * Calls the token endpoint (RFC 6749 §3.2), sending client_id / secret per the client's auth method
+ * (Basic form-encodes them first, §2.3.1).
+ * - 400 / 401 with a parsable RFC 6749 `error` code -> OAuthGrantError.
+ * - 200 with `ok: false` (Slack reports every error this way), or with an `error` code and no
+ *   `access_token` -> OAuthGrantError with that code (`ok: false` wins over an `access_token`); a
+ *   transient code (`temporarily_unavailable`, `server_error`, Slack's `ratelimited`, ...) or no
+ *   parsable code -> OAuthUnavailable.
+ * - Everything else (network error, timeout, 429, 408, 403 and other 4xx, a 4xx without a code,
+ *   5xx, 3xx, a malformed body) -> OAuthUnavailable: a gateway's rate limit or a WAF block is not a
+ *   dead credential.
+ * - A `token_type` other than Bearer / `user` / `opts.tokenTypes` -> OAuthGrantError
+ *   `unsupported_token_type`; an accepted one is stored as `Bearer`.
  */
-export async function tokenRequest(client, params, http) {
+export async function tokenRequest(client, params, http, opts = {}) {
     const form = new URLSearchParams();
     for (const [k, v] of Object.entries(params))
         if (v !== undefined && v !== "")
@@ -86,11 +123,19 @@ export async function tokenRequest(client, params, http) {
     }
     if (res.status !== 200 || !isObj(body))
         throw new OAuthUnavailable();
+    if (body.ok === false || (body.access_token === undefined && body.error !== undefined)) {
+        const code = body.error;
+        if (typeof code === "string" && OAUTH_ERROR_RE.test(code) && !TRANSIENT_ERRORS.has(code)) {
+            throw new OAuthGrantError(code);
+        }
+        throw new OAuthUnavailable();
+    }
     const { access_token, refresh_token, expires_in, token_type, scope } = body;
     if (typeof access_token !== "string" || access_token === "")
         throw new OAuthUnavailable();
-    const type = typeof token_type === "string" ? token_type : "Bearer";
-    if (type.toLowerCase() !== "bearer")
+    const type = (typeof token_type === "string" ? token_type : "Bearer").toLowerCase();
+    const accepted = BEARER_TOKEN_TYPES.has(type) || opts.tokenTypes?.some((t) => t.toLowerCase() === type);
+    if (!accepted)
         throw new OAuthGrantError("unsupported_token_type");
     return {
         access_token,
@@ -102,30 +147,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 +210,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 +218,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 +243,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 +255,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();
             }
@@ -228,14 +274,14 @@ export class OAuthTokens {
                     grant_type: "refresh_token",
                     refresh_token: rec.refresh_token,
                     resource: client.resource,
-                }, this.http());
+                }, this.http(), { tokenTypes: auth.tokenTypes });
                 // 授权服务器不轮换时沿用旧 refresh token
                 if (next.refresh_token === undefined)
                     next = { ...next, refresh_token: rec.refresh_token };
             }
             else {
                 const scopes = auth.scopes ?? client.scopes;
-                next = await tokenRequest(client, { grant_type: "client_credentials", scope: scopes?.join(" "), resource: client.resource }, this.http());
+                next = await tokenRequest(client, { grant_type: "client_credentials", scope: scopes?.join(" "), resource: client.resource }, this.http(), { tokenTypes: auth.tokenTypes });
             }
         }
         catch (e) {

package/dist/tools/org-tool-switches.d.ts

@@ -0,0 +1,88 @@
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+/** One tool of an extension with its switch in the org. */
+export interface OrgToolSwitch {
+    tool: string;
+    enabled: boolean;
+}
+/** An org agent whose current version selects the tool being switched off. */
+export interface AffectedAgent {
+    id: string;
+    name: string;
+}
+/**
+ * The result of {@link OrgToolSwitches.set}: the PCM §5 rule 8 preview of a switch-off (the org's
+ * agents that selected the tool and the hash to confirm it with), or the switch applied.
+ */
+export type OrgToolSwitchResult = {
+    applied: false;
+    affectedAgents: AffectedAgent[];
+    confirm: string;
+} | {
+    applied: true;
+};
+/** Model-visible (English): why a turned-off extension tool is not offered. */
+export declare const toolTurnedOffReason: (key: string) => string;
+/**
+ * Per-org switches of single extension tools (layering spec A §7, table `org_tool_switches`): an
+ * org admin turns off one tool an extension registers (`ctx.tools.register`); it is then not
+ * offered to any agent of the org (`ToolRegistry.forAgent`) and refused if called
+ * (`ToolPipeline`). No row means on. A row of a tool the extension stops registering is kept and
+ * applies again if the tool comes back. Builtin and connector tools are out of scope. Read from PG
+ * on every use, no in-process state.
+ */
+export declare class OrgToolSwitches {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly host;
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    private readonly orgLock;
+    constructor(kdb: KernelDb, txHost: TransactionHost, host: Pick<ExtensionHost, "tools">, 
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    orgLock: Pick<OrgLock, "lockAndAuthorize">);
+    private get db();
+    /** The tool names `plugin` registers on this replica, in registration order. */
+    private registered;
+    /**
+     * The tools of an extension the org sees: running here and visible under plugin scope, else 404
+     * `extension.not_found` (an invisible one is answered like an unknown one).
+     */
+    private toolsFor;
+    /** The stored switches of the org (all extensions, or one), `false` ones only matter. */
+    private offRows;
+    /** Every tool the extension registers on this replica with its switch (default on). */
+    list(orgId: string, plugin: string): Promise<OrgToolSwitch[]>;
+    /**
+     * What turning one tool off would affect (nothing written): the agents selecting it and the
+     * confirm hash {@link set} takes, or null when it is off already. Unknown tool -> 404
+     * `extension.tool_not_found`.
+     */
+    previewOff(orgId: string, plugin: string, tool: string): Promise<{
+        affectedAgents: AffectedAgent[];
+        confirm: string;
+    } | null>;
+    /** The model-visible keys (`plugin__<extension>__<tool>`) of the tools turned off in the org. */
+    offKeys(orgId: string): Promise<Set<string>>;
+    /** Whether the org turned off this tool. */
+    isToolOff(orgId: string, plugin: string, tool: string): Promise<boolean>;
+    /**
+     * Switches one tool in the org. On applies at once. Off, while the tool is on: without
+     * `confirm` the preview (the org's agents whose current version does not turn it off) and its hash,
+     * with the current hash the switch is written (a changed preview -> 409 `plugin.switch_stale`).
+     * A tool the extension does not register -> 404 `extension.tool_not_found`. A change writes the
+     * audit row `extension.tool_switched`.
+     */
+    set(orgId: string, plugin: string, tool: string, enabled: boolean, actor: {
+        accountId: string;
+        tokenId?: string | undefined;
+        /** Merged into the audit detail (a write made through the Platform tool). */
+        auditDetail?: Record<string, unknown>;
+    }, confirm?: string): Promise<OrgToolSwitchResult>;
+    /**
+     * The org's live agents whose current version has extension tool `tool` of `plugin` on: tools
+     * are on by default (tools default-on spec §4), so every agent that does not turn it off.
+     */
+    private agentsSelecting;
+}

package/dist/tools/org-tool-switches.js

@@ -0,0 +1,201 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from "node:crypto";
+import { extensionToolKey } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { extensionToolDisabled } from "../agents/definition.js";
+import { ApiError } from "../errors.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { extensionVisibleTo } from "../extensions/org-config.js";
+import { audit } from "../identity/audit.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 { OrgLock } from "../orgs/org-lock.js";
+/** Model-visible (English): why a turned-off extension tool is not offered. */
+export const toolTurnedOffReason = (key) => `Tool ${key} is turned off in this organization`;
+/** The confirm hash of a switch-off preview. */
+function switchOffHash(orgId, plugin, tool, agents) {
+    return createHash("sha256")
+        .update(JSON.stringify({ orgId, plugin, tool, agents: agents.map((a) => a.id) }))
+        .digest("hex");
+}
+/**
+ * Per-org switches of single extension tools (layering spec A §7, table `org_tool_switches`): an
+ * org admin turns off one tool an extension registers (`ctx.tools.register`); it is then not
+ * offered to any agent of the org (`ToolRegistry.forAgent`) and refused if called
+ * (`ToolPipeline`). No row means on. A row of a tool the extension stops registering is kept and
+ * applies again if the tool comes back. Builtin and connector tools are out of scope. Read from PG
+ * on every use, no in-process state.
+ */
+let OrgToolSwitches = class OrgToolSwitches {
+    kdb;
+    txHost;
+    host;
+    orgLock;
+    constructor(kdb, txHost, host, 
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    orgLock) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.host = host;
+        this.orgLock = orgLock;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** The tool names `plugin` registers on this replica, in registration order. */
+    registered(plugin) {
+        return [
+            ...new Set(this.host
+                .tools()
+                .filter((t) => t.plugin === plugin)
+                .map((t) => t.spec.name)),
+        ];
+    }
+    /**
+     * The tools of an extension the org sees: running here and visible under plugin scope, else 404
+     * `extension.not_found` (an invisible one is answered like an unknown one).
+     */
+    async toolsFor(orgId, plugin) {
+        const tools = this.registered(plugin);
+        if (tools.length === 0 || !(await extensionVisibleTo(this.db, orgId, plugin))) {
+            throw new ApiError("extension.not_found", `Extension ${plugin} is not installed`);
+        }
+        return tools;
+    }
+    /** The stored switches of the org (all extensions, or one), `false` ones only matter. */
+    async offRows(orgId, plugin) {
+        let q = this.db
+            .selectFrom("org_tool_switches")
+            .select(["plugin", "tool"])
+            .where("org_id", "=", orgId)
+            .where("enabled", "=", false);
+        if (plugin !== undefined)
+            q = q.where("plugin", "=", plugin);
+        return q.execute();
+    }
+    /** Every tool the extension registers on this replica with its switch (default on). */
+    async list(orgId, plugin) {
+        const tools = await this.toolsFor(orgId, plugin);
+        const off = new Set((await this.offRows(orgId, plugin)).map((r) => r.tool));
+        return tools.map((tool) => ({ tool, enabled: !off.has(tool) }));
+    }
+    /**
+     * What turning one tool off would affect (nothing written): the agents selecting it and the
+     * confirm hash {@link set} takes, or null when it is off already. Unknown tool -> 404
+     * `extension.tool_not_found`.
+     */
+    async previewOff(orgId, plugin, tool) {
+        const tools = await this.toolsFor(orgId, plugin);
+        if (!tools.includes(tool)) {
+            throw new ApiError("extension.tool_not_found", `Extension ${plugin} does not register a tool named ${tool}`);
+        }
+        if (await this.isToolOff(orgId, plugin, tool))
+            return null;
+        const affectedAgents = await this.agentsSelecting(orgId, plugin, tool);
+        return { affectedAgents, confirm: switchOffHash(orgId, plugin, tool, affectedAgents) };
+    }
+    /** The model-visible keys (`plugin__<extension>__<tool>`) of the tools turned off in the org. */
+    async offKeys(orgId) {
+        return new Set((await this.offRows(orgId)).map((r) => extensionToolKey(r.plugin, r.tool)));
+    }
+    /** Whether the org turned off this tool. */
+    async isToolOff(orgId, plugin, tool) {
+        const row = await this.db
+            .selectFrom("org_tool_switches")
+            .select("enabled")
+            .where("org_id", "=", orgId)
+            .where("plugin", "=", plugin)
+            .where("tool", "=", tool)
+            .executeTakeFirst();
+        return row?.enabled === false;
+    }
+    /**
+     * Switches one tool in the org. On applies at once. Off, while the tool is on: without
+     * `confirm` the preview (the org's agents whose current version does not turn it off) and its hash,
+     * with the current hash the switch is written (a changed preview -> 409 `plugin.switch_stale`).
+     * A tool the extension does not register -> 404 `extension.tool_not_found`. A change writes the
+     * audit row `extension.tool_switched`.
+     */
+    async set(orgId, plugin, tool, enabled, actor, confirm) {
+        await this.orgLock.lockAndAuthorize(orgId, actor.accountId, "org.extensions.manage");
+        const tools = await this.toolsFor(orgId, plugin);
+        if (!tools.includes(tool)) {
+            throw new ApiError("extension.tool_not_found", `Extension ${plugin} does not register a tool named ${tool}`);
+        }
+        const from = !(await this.isToolOff(orgId, plugin, tool));
+        if (from === enabled)
+            return { applied: true };
+        if (!enabled) {
+            const affectedAgents = await this.agentsSelecting(orgId, plugin, tool);
+            const hash = switchOffHash(orgId, plugin, tool, affectedAgents);
+            if (confirm === undefined)
+                return { applied: false, affectedAgents, confirm: hash };
+            if (confirm !== hash) {
+                throw new ApiError("plugin.switch_stale", "What switching this tool off affects has changed; review it and confirm again");
+            }
+        }
+        await this.db
+            .insertInto("org_tool_switches")
+            .values({ org_id: orgId, plugin, tool, enabled, updated_by: actor.accountId })
+            .onConflict((oc) => oc.columns(["org_id", "plugin", "tool"]).doUpdateSet({
+            enabled,
+            updated_by: actor.accountId,
+            updated_at: sql `now()`,
+        }))
+            .execute();
+        await audit(this.db, {
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+            orgId,
+            action: "extension.tool_switched",
+            target: extensionToolKey(plugin, tool),
+            detail: { plugin, tool, from, to: enabled, ...actor.auditDetail },
+        });
+        return { applied: true };
+    }
+    /**
+     * The org's live agents whose current version has extension tool `tool` of `plugin` on: tools
+     * are on by default (tools default-on spec §4), so every agent that does not turn it off.
+     */
+    async agentsSelecting(orgId, plugin, tool) {
+        const rows = await this.db
+            .selectFrom("agents as a")
+            .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
+            .select(["a.id", "v.definition"])
+            .where("a.org_id", "=", orgId)
+            .where("a.deleted_at", "is", null)
+            .orderBy("a.id")
+            .execute();
+        const out = [];
+        for (const r of rows) {
+            const def = r.definition;
+            const off = Array.isArray(def?.disabledTools)
+                ? extensionToolDisabled(def.disabledTools, plugin, tool)
+                : false;
+            if (!off)
+                out.push({ id: r.id, name: typeof def?.name === "string" ? def.name : r.id });
+        }
+        return out;
+    }
+};
+__decorate([
+    Transactional()
+], OrgToolSwitches.prototype, "set", null);
+OrgToolSwitches = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(ExtensionHost)),
+    __param(3, Inject(OrgLock))
+], OrgToolSwitches);
+export { OrgToolSwitches };

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;
 /**