@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/tools/drift.js

@@ -1,12 +1,29 @@
-import { TOOL_TITLE_MAX, ToolError, validateToolPresentation, } from "@capybara-hq/plugin-sdk";
+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 { connectorToolKey, 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 { toolKey, toolKeyIssue } from "./naming.js";
+import { CredentialMissing, Credentials, isOAuth } from "./credentials.js";
+import { 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，不含 `:`）。
  */
@@ -91,7 +105,7 @@ export function snapshot(slug, specs, resources) {
             ...(isObj(s.connectorData) && { connectorData: s.connectorData }),
             ...displayFields(s),
         };
-        let issue = toolKeyIssue(toolKey(slug, name));
+        let issue = toolKeyIssue(connectorToolKey(slug, name));
         if (!issue && !isObj(s.inputSchema))
             issue = "Tool inputSchema must be an object";
         if (issue)
@@ -108,7 +122,7 @@ export function snapshot(slug, specs, resources) {
                 });
                 continue;
             }
-            const issue = toolKeyIssue(toolKey(slug, spec.name));
+            const issue = toolKeyIssue(connectorToolKey(slug, spec.name));
             if (issue)
                 issues.push({ name: spec.name, reason: issue });
             rows.push({ name: spec.name, spec, specHash: specHash(spec), issue, source: "resources" });
@@ -158,7 +172,7 @@ const displayOf = (spec) => {
 };
 /** 工具当前不能启用的原因（视图、启用与复核校验共用）。 */
 export function toolIssue(slug, spec) {
-    const keyIssue = toolKeyIssue(toolKey(slug, spec.name));
+    const keyIssue = toolKeyIssue(connectorToolKey(slug, spec.name));
     if (keyIssue)
         return keyIssue;
     if (!isObj(spec.inputSchema))
@@ -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/elicitation.js

@@ -33,7 +33,7 @@ export class ElicitationSuspended extends Error {
 }
 /** 不能展示的 elicitation 被拒绝时附在工具结果后的说明（模型可见，英文）。 */
 export const UNSUPPORTED_ELICITATION_NOTE = "The app asked the user for input that cannot be shown in this client, so the request was declined";
-const unsupportedNote = (why) => `[${UNSUPPORTED_ELICITATION_NOTE} (${why}). If the call needs that input, ask the user for it with ask_user and pass it as tool arguments, or try another approach.]`;
+const unsupportedNote = (why) => `[${UNSUPPORTED_ELICITATION_NOTE} (${why}). If the call needs that input, ask the user for it with AskUserQuestion and pass it as tool arguments, or try another approach.]`;
 /** URL 模式表单里「已完成」开关的字段名。 */
 export const URL_COMPLETED_FIELD = "completed";
 /** 表单标题（远端给的 message）最多字符数。 */

package/dist/tools/extension-tools.controller.d.ts

@@ -0,0 +1,14 @@
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type ExtensionToolsOffer, OrgExtensionTools } from "./info.js";
+/**
+ * `GET /api/v1/orgs/:orgId/tools/extensions` (`agents.use`) → `{ extensions }`: the tools of the
+ * extensions enabled in the org, grouped by extension, for the agent form's Tools section (it adds
+ * or removes `{kind:"plugin",plugin,name}` references). Display only; nothing here is model-visible.
+ */
+export declare class ExtensionToolsController {
+    private readonly tools;
+    constructor(tools: OrgExtensionTools);
+    extensions(org: OrgContext): Promise<{
+        extensions: ExtensionToolsOffer[];
+    }>;
+}

package/dist/tools/extension-tools.controller.js

@@ -0,0 +1,37 @@
+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 { Controller, Get, Header, Inject } from "@nestjs/common";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { OrgExtensionTools } from "./info.js";
+/**
+ * `GET /api/v1/orgs/:orgId/tools/extensions` (`agents.use`) → `{ extensions }`: the tools of the
+ * extensions enabled in the org, grouped by extension, for the agent form's Tools section (it adds
+ * or removes `{kind:"plugin",plugin,name}` references). Display only; nothing here is model-visible.
+ */
+let ExtensionToolsController = class ExtensionToolsController {
+    tools;
+    constructor(tools) {
+        this.tools = tools;
+    }
+    async extensions(org) {
+        return { extensions: await this.tools.list(org.orgId) };
+    }
+};
+__decorate([
+    Get("extensions"),
+    Header("cache-control", "private, no-store"),
+    OrgAction("agents.use"),
+    __param(0, CurrentOrg())
+], ExtensionToolsController.prototype, "extensions", null);
+ExtensionToolsController = __decorate([
+    Controller("api/v1/orgs/:orgId/tools"),
+    __param(0, Inject(OrgExtensionTools))
+], ExtensionToolsController);
+export { ExtensionToolsController };

package/dist/tools/info.d.ts

@@ -1,5 +1,9 @@
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { ToolRegistry } from "./registry.js";
+import { type LocalizedName, type ToolAnnotations } from "@capybara-hq/plugin-sdk";
+import { ConversationAccess } from "../conversations/access.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { OrgToolSwitches } from "./org-tool-switches.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.
@@ -9,16 +13,32 @@ export type ToolKind = "command" | "read" | "edit" | "search" | "connector" | "m
 export interface ToolInfo {
     /** The model-visible tool key, as asked for. */
     key: string;
+    /**
+     * Set only for a release-candidate builtin key (old history, tool naming spec §9): the current
+     * tool it stands for. Everything else describes that tool, with `keyArgs` in the old parameter
+     * names the logged input carries. Pages map a call's name through it (the `Agent` row, labels).
+     */
+    aliasOf?: string;
     /** The declared display title (`ToolSpec.title`), or null. */
     title: string | null;
     kind: ToolKind;
+    /** True exactly for the builtin tools that run in the conversation's sandbox. */
+    sandbox: boolean;
     /** The declared key arguments (`ToolSpec.keyArgs`), or []. */
     keyArgs: string[];
+    /**
+     * The local tool name parsed from a connector or extension key (`mcp__crm__delete` -> `delete`),
+     * shown in brackets after the source's display name; null for builtins and unparsable keys.
+     */
+    tool: string | null;
     source: {
         kind: "builtin";
-    } | {
+    }
+    /** `displayName`: the plugin's catalog display name, else its name. */
+     | {
         kind: "extension";
         name: string;
+        displayName: LocalizedName;
     } | {
         kind: "connector";
         id: string;
@@ -29,18 +49,17 @@ export interface ToolInfo {
         kind: "unknown";
     };
 }
-/** Kinds of the kernel builtin tools; a builtin missing here is a plain `tool`. */
-export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
+export { BUILTIN_TOOL_KINDS } from "./builtin-names.js";
 /** At most this many keys per request, each at most {@link TOOL_INFO_KEY_MAX} characters. */
 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">;
 }
 /**
  * Presentation metadata for `keys` in this org, in request order with repeats dropped. Builtins
- * by name; `<prefix>__<tool>` keys first as a loaded extension's registration, then as a live
+ * by name (a release-candidate builtin key as its current tool, with `aliasOf`); `plugin__<plugin>__<tool>` keys as a loaded extension's registration, and `mcp__<slug>__<tool>` keys as a live
  * connector's current stored tool (its reviewed definition, never a pending one). Anything else
  * comes back as an unknown plain tool.
  *
@@ -55,13 +74,54 @@ 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[]>;
 }
+/** One tool of {@link OrgExtensionTools}. Display only, for the agent form. */
+export interface ExtensionToolOffer {
+    /** The tool's registered name (the `name` of a `{kind:"plugin"}` reference). */
+    name: string;
+    /** The model-visible key, `plugin__<plugin>__<name>` (the `toolPolicies` key). */
+    key: string;
+    /** The declared display title (`ToolSpec.title`), or null. */
+    title: string | null;
+    /** The first non-empty line of the tool's description (English, model-facing text). */
+    description: string;
+    annotations: ToolAnnotations;
+    /** The tool's default policy: its `defaultPolicy`, else derived from the annotations. */
+    defaultPolicy: "allow" | "ask";
+    /**
+     * The org turned this tool off (layering spec A §7): still listed, so the form shows it as
+     * unavailable in the agents that selected it.
+     */
+    switchedOff: boolean;
+}
+/** One extension of {@link OrgExtensionTools} with its tools, in registration order. */
+export interface ExtensionToolsOffer {
+    plugin: string;
+    /** The plugin's catalog display name, else its name. */
+    displayName: LocalizedName;
+    tools: ExtensionToolOffer[];
+}
+/**
+ * `GET /orgs/:orgId/tools/extensions`: the tools an agent of this org can reference by
+ * `{kind:"plugin"}` and get at run time, grouped by extension: the extensions loaded on this
+ * replica and enabled in the org (`enabled.ts`, through the host), each with the tools it
+ * registered whose key is valid (`ToolRegistry.forAgent` reports the others unavailable); a tool
+ * the org turned off is listed with `switchedOff`.
+ */
+export declare class OrgExtensionTools {
+    private readonly db;
+    private readonly registry;
+    private readonly switches;
+    constructor(db: KernelDb, registry: Pick<ToolRegistry, "extensionToolSpecs" | "enabledExtensions">, switches: Pick<OrgToolSwitches, "offKeys">);
+    list(orgId: string): Promise<ExtensionToolsOffer[]>;
+}