@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/tools/connectors.controller.js

@@ -0,0 +1,234 @@
+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 { ConnectorAuthSchema } from "@capybara-hq/plugin-sdk";
+import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, Put, } from "@nestjs/common";
+import { z } from "zod";
+import { CONNECTORS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { can } from "../orgs/roles.js";
+import { publicEndpoint } from "./endpoint.js";
+/**
+ * 没有 `connectors.manage` 的读者只看到端点的公开部分（URL 不带 query、只有头名，见 endpoint.ts），
+ * 也看不到工具的连接器数据（可能含服务器地址）。
+ */
+function forViewer(org, c) {
+    if (can(org.role, "connectors.manage"))
+        return c;
+    const view = { ...c, endpoint: publicEndpoint(c.endpoint) };
+    if ("tools" in view) {
+        view.tools = view.tools.map((t) => ({
+            ...t,
+            connectorData: null,
+            pending: t.pending && { ...t.pending, connectorData: null },
+        }));
+    }
+    return view;
+}
+/** 凭据值：形状由 `Credentials.validate` 按认证方式校验（不回显值）；这里只限大小。 */
+export const CredentialValue = z
+    .record(z.string().max(100), z.unknown())
+    .refine((v) => JSON.stringify(v).length <= 16_384, { message: "Credential is too large" });
+const CreateBody = z
+    .object({
+    name: z.string().trim().min(1).max(80),
+    slug: z.string().max(24).optional(),
+    connector: z.string().min(1).max(100),
+    endpoint: z.record(z.string(), z.unknown()),
+    auth: ConnectorAuthSchema,
+    credential: CredentialValue.optional(),
+})
+    .strict();
+/** 预览（Ruling A20）：与创建相同的连接器 / 端点 / 认证 / 凭据，认证可缺省（只读端点描述，不列工具）。 */
+const PreviewBody = z
+    .object({
+    name: z.string().trim().min(1).max(80).optional(),
+    slug: z.string().max(24).optional(),
+    connector: z.string().min(1).max(100),
+    endpoint: z.record(z.string(), z.unknown()),
+    auth: ConnectorAuthSchema.optional(),
+    credential: CredentialValue.optional(),
+})
+    .strict();
+const ToolPatch = z
+    .object({
+    status: z.enum(["enabled", "disabled"]).optional(),
+    defaultPolicy: z.enum(["allow", "ask", "deny"]).optional(),
+})
+    .strict();
+const ReviewBody = z.object({ action: z.enum(["approve", "reject"]) }).strict();
+const UpdateBody = z
+    .object({
+    name: z.string().trim().min(1).max(80).optional(),
+    status: z.enum(["active", "disabled"]).optional(),
+    tools: z
+        .record(z.string().max(200), ToolPatch)
+        .refine((v) => Object.keys(v).length <= 1000, { message: "Too many tools" })
+        .optional(),
+    allowUnannotated: z.boolean().optional(),
+})
+    .strict();
+/**
+ * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
+ * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
+ */
+let ConnectorsController = class ConnectorsController {
+    connectors;
+    constructor(connectors) {
+        this.connectors = connectors;
+    }
+    async list(org) {
+        return { connectors: (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a)) };
+    }
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        return this.connectors.create(org.orgId, p.account.id, body, patTokenId(p));
+    }
+    /**
+     * 预览（安装向导）：读端点描述（认证提示、操作清单）并在能认证时列出工具，什么都不写。
+     * 创建与预览的请求体可带最大 2 MB 的 OpenAPI 文档，路由级 bodyLimit 见 http/app.ts。
+     */
+    async preview(principal, org, body) {
+        requireUser(principal);
+        return this.connectors.preview(org.orgId, body);
+    }
+    async get(principal, org, connectorId) {
+        const p = requireUser(principal);
+        return {
+            connector: forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id)),
+        };
+    }
+    async update(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        return {
+            connector: await this.connectors.update(org.orgId, connectorId, p.account.id, body, patTokenId(p)),
+        };
+    }
+    async remove(principal, org, connectorId) {
+        const p = requireUser(principal);
+        await this.connectors.remove(org.orgId, connectorId, p.account.id, patTokenId(p));
+    }
+    async refresh(principal, org, connectorId) {
+        const p = requireUser(principal);
+        return this.connectors.refresh(org.orgId, connectorId, p.account.id, patTokenId(p));
+    }
+    /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
+    async review(principal, org, connectorId, name, body) {
+        const p = requireUser(principal);
+        return {
+            connector: await this.connectors.reviewTool(org.orgId, connectorId, name, body.action, p.account.id, patTokenId(p)),
+        };
+    }
+    async setOrgCredential(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        await this.connectors.setCredential(org.orgId, connectorId, p.account.id, "org", body, patTokenId(p));
+    }
+    async setMyCredential(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        await this.connectors.setCredential(org.orgId, connectorId, p.account.id, "personal", body, patTokenId(p));
+    }
+    async clearMyCredential(principal, org, connectorId) {
+        const p = requireUser(principal);
+        await this.connectors.clearMyCredential(org.orgId, connectorId, p.account.id, patTokenId(p));
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("connectors.use"),
+    __param(0, CurrentOrg())
+], ConnectorsController.prototype, "list", null);
+__decorate([
+    Post(),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(CreateBody)))
+], ConnectorsController.prototype, "create", null);
+__decorate([
+    Post("preview"),
+    HttpCode(200),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(PreviewBody)))
+], ConnectorsController.prototype, "preview", null);
+__decorate([
+    Get(":connectorId"),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId"))
+], ConnectorsController.prototype, "get", null);
+__decorate([
+    Patch(":connectorId"),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, Body(new ZodPipe(UpdateBody)))
+], ConnectorsController.prototype, "update", null);
+__decorate([
+    Delete(":connectorId"),
+    HttpCode(204),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId"))
+], ConnectorsController.prototype, "remove", null);
+__decorate([
+    Post(":connectorId/refresh"),
+    HttpCode(200),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId"))
+], ConnectorsController.prototype, "refresh", null);
+__decorate([
+    Post(":connectorId/tools/:name/review"),
+    HttpCode(200),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, Param("name")),
+    __param(4, Body(new ZodPipe(ReviewBody)))
+], ConnectorsController.prototype, "review", null);
+__decorate([
+    Put(":connectorId/credentials/org"),
+    HttpCode(204),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, Body(new ZodPipe(CredentialValue)))
+], ConnectorsController.prototype, "setOrgCredential", null);
+__decorate([
+    Put(":connectorId/credentials/me"),
+    HttpCode(204),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, Body(new ZodPipe(CredentialValue)))
+], ConnectorsController.prototype, "setMyCredential", null);
+__decorate([
+    Delete(":connectorId/credentials/me"),
+    HttpCode(204),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId"))
+], ConnectorsController.prototype, "clearMyCredential", null);
+ConnectorsController = __decorate([
+    Controller("api/v1/orgs/:orgId/connectors"),
+    __param(0, Inject(CONNECTORS))
+], ConnectorsController);
+export { ConnectorsController };

package/dist/tools/connectors.service.d.ts

@@ -0,0 +1,303 @@
+import { type AuthHint, type ConnectorOperation, type ToolAnnotations } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { ExtensionHost } from "../extensions/host.js";
+import { type ConnectorAuth, type CredentialOwner, type Credentials, type StaticSecret } from "./credentials.js";
+import { type DriftChanges, type ToolDrift, type ToolIssue } from "./drift.js";
+import { type OAuthClientRecord, type OAuthTokenRecord } from "./oauth/tokens.js";
+import { type ToolPolicy, type ToolRegistry } from "./registry.js";
+type Trx = Transaction<KernelDatabase>;
+export type { ToolIssue } from "./drift.js";
+type ToolStatus = "enabled" | "disabled" | "pending_review";
+type ToolSource = "connector" | "resources";
+/** 连接器工具视图；`issue` 非空表示该工具不能启用的原因（如 key 超长）。 */
+export interface ConnectorToolView {
+    name: string;
+    key: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: ToolAnnotations | null;
+    /**
+     * 连接器的不透明路由数据（Ruling A21，如 OpenAPI 的方法 / 路径 / 服务器地址），供复核对比；没有时为 null。
+     * 只给 `connectors.manage`（读者视图里置 null，见 connectors.controller.ts）。
+     */
+    connectorData: Record<string, unknown> | null;
+    status: ToolStatus;
+    defaultPolicy: ToolPolicy;
+    specHash: string;
+    issue: string | null;
+    /** `resources`：内核为支持 resources 的连接器补上的工具（见 resources.ts）。 */
+    source: ToolSource;
+    /**
+     * 默认策略的来历：`derived` 按注解推导（定义变化复核通过后重新推导），`admin` 管理员设定（保留），
+     * `template` 来自目录模板的 `defaultToolPolicies`（与 admin 一样保留）。
+     */
+    policySource: "derived" | "admin" | "template";
+    /** 远端已不再提供该工具（随之停用；又出现时待复核）。 */
+    missing: boolean;
+    reviewedAt: Date | null;
+    /**
+     * 定义变化后待复核的新定义（漂移检测，Task 17）；上面的 description / inputSchema / annotations / specHash /
+     * source 是当前（上次复核通过的）定义，供对比。新增的待复核工具没有旧定义，此处为 null。
+     */
+    pending: {
+        description: string;
+        inputSchema: Record<string, unknown>;
+        annotations: ToolAnnotations | null;
+        connectorData: Record<string, unknown> | null;
+        specHash: string;
+        source: ToolSource;
+    } | null;
+}
+/** 列表项：不含工具与凭据（`auth` 只有类型与非密钥字段）。 */
+export interface ConnectorSummary {
+    id: string;
+    slug: string;
+    name: string;
+    connector: string;
+    endpoint: unknown;
+    auth: ConnectorAuth;
+    status: "active" | "disabled";
+    createdBy: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ConnectorDetail extends ConnectorSummary {
+    tools: ConnectorToolView[];
+    /** 当前用户视角的凭据状态；`ownership` 为 null 表示无需凭据（auth none）。 */
+    credential: {
+        ownership: "org" | "personal" | null;
+        status: "connected" | "missing";
+    };
+}
+export interface CreateConnectorInput {
+    name: string;
+    slug?: string | undefined;
+    connector: string;
+    endpoint: unknown;
+    auth: ConnectorAuth;
+    credential?: unknown;
+    /**
+     * Install from an enterprise catalog connector template (T26, filled in by the catalog service,
+     * not accepted over HTTP): the connector records its source item and version, the item policy is
+     * re-checked in the transaction (a template inside an app passes the app item); once the tool
+     * snapshot exists, `defaultToolPolicies` set the default policies (`policy_source 'template'`).
+     * Absent = custom; rejected when the deployment setting `customConnectors` is deny
+     * (`catalog.custom_disabled`).
+     */
+    template?: ConnectorTemplateRef | undefined;
+}
+/** 连接器来自哪个目录条目的哪个模板。 */
+export interface ConnectorTemplateRef {
+    itemId: string;
+    version: string;
+    /** 应用里的模板 id；独立的连接器模板条目为空。 */
+    templateId?: string | undefined;
+    defaultToolPolicies?: Record<string, ToolPolicy> | undefined;
+    /** The item whose policy approves this install (a dependency's template: the installed plugin). */
+    approvedBy?: string | undefined;
+}
+/**
+ * A connector updated to another version of its catalog template (an org plugin upgrade, package
+ * ecosystem spec §10): only template-owned fields change (endpoint preset, auth preset, default tool
+ * policies still at the template default); the name, slug, status, tools and credentials stay,
+ * unless `resetCredentials`.
+ */
+export interface TemplateUpdateInput {
+    /** The new template's endpoint preset with the org's values at its editable paths. */
+    endpoint: unknown;
+    auth: ConnectorAuth;
+    /** The template version (itemId, version, templateId, defaultToolPolicies). */
+    template: ConnectorTemplateRef;
+    /**
+     * The auth method or the credentials it needs changed: the connector's credentials (org and
+     * personal, OAuth client and tokens) are cleared and `credential` (an org or the actor's static
+     * credential, or the OAuth client) is set.
+     */
+    resetCredentials: boolean;
+    credential?: unknown;
+}
+/** A {@link TemplateUpdateInput} checked by {@link ConnectorsService.prepareTemplateUpdate}. */
+export interface PreparedTemplateUpdate {
+    input: TemplateUpdateInput;
+    endpoint: unknown;
+    owner?: CredentialOwner;
+    secret?: StaticSecret;
+    oauth?: OAuthSetup;
+}
+export interface PreviewConnectorInput {
+    name?: string | undefined;
+    slug?: string | undefined;
+    connector: string;
+    endpoint: unknown;
+    auth?: ConnectorAuth | undefined;
+    credential?: unknown;
+}
+/** 预览里的一个工具：与安装后的工具视图同形的子集（`issue` 非空 = 安装后只能停用）。 */
+export interface ToolPreview {
+    name: string;
+    key: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: ToolAnnotations | null;
+    defaultPolicy: ToolPolicy;
+    issue: string | null;
+    source: ToolSource;
+}
+/**
+ * 连接器预览（Ruling A20）：`tools` 为 null 表示没有列工具（没给认证方式、需要凭据但没给、OAuth 授权码流）；
+ * `authHints` / `operations` 来自连接器的 `inspect`（不实现时为空 / 缺省）。
+ */
+export interface ConnectorPreview {
+    tools: ToolPreview[] | null;
+    /** 列工具时被停用 / 跳过的工具及原因（与安装时的 issues 相同；同名工具只保留第一个）。 */
+    issues: ToolIssue[];
+    authHints: AuthHint[];
+    operations?: ConnectorOperation[];
+}
+export interface UpdateConnectorInput {
+    name?: string | undefined;
+    status?: "active" | "disabled" | undefined;
+    tools?: Record<string, {
+        status?: "enabled" | "disabled" | undefined;
+        defaultPolicy?: ToolPolicy | undefined;
+    }> | undefined;
+    /** 把「没有 readOnlyHint / destructiveHint 注解」的工具默认策略批量改为 allow。 */
+    allowUnannotated?: boolean | undefined;
+}
+/** OAuth 安装准备的结果：要存的客户端，以及（客户端凭据流）安装时取到的组织 token。 */
+export interface OAuthSetup {
+    client: OAuthClientRecord;
+    tokens?: OAuthTokenRecord;
+}
+/**
+ * 连接器（远端服务实例）与其工具快照、凭据。写操作都在组织行锁内复核发起人权限并写审计
+ * （detail 只有凭据类型与归属，没有值）。连接器会话按操作打开、用完即关，不在进程内缓存。
+ */
+export declare class ConnectorsService {
+    private readonly db;
+    private readonly registry;
+    private readonly host;
+    private readonly credentials;
+    private readonly config;
+    private readonly drift;
+    constructor(db: KernelDb, registry: ToolRegistry, host: ExtensionHost, credentials: Credentials, config: () => KernelConfig, drift: ToolDrift);
+    /**
+     * 校验连接器存在、端点按其 schema 合法、不含凭据样式的头 / query 参数 / URL 用户信息（端点对成员可见，
+     * 凭据须走认证设置）；返回解析后的端点。
+     */
+    private parseEndpoint;
+    private slugTaken;
+    private resolveSlug;
+    /**
+     * OAuth 连接器安装前的准备（A16）：授权码流按 `discovery` 取端点（MCP 发现或手填）、按 `client` 动态注册或用请求里
+     * 手填的 client（不做首次 listTools）；客户端凭据流用请求里的 client 取一次组织 token。
+     * 外连失败一律 502 `connector.connect_failed`（details 带原因码），什么都不写。
+     */
+    private prepareOAuth;
+    /**
+     * The checks of {@link create} that need neither a connection nor the database: the slug, the
+     * endpoint against the connector's schema, the credential shape, the OAuth client and the OAuth
+     * URL policy. `create` runs them first; a plugin install runs them for every template before it
+     * creates anything, so bad input is a 400 rather than a failed install. Returns what they parsed.
+     */
+    checkCreateInput(actorAccountId: string, input: CreateConnectorInput): {
+        slug: string;
+        endpoint: unknown;
+        owner?: CredentialOwner;
+        secret?: StaticSecret;
+    };
+    /**
+     * 安装连接器（A4）：校验 → 用请求里的凭据（尚未落库）连接并 listTools → 一个事务内写连接器、工具快照、
+     * 凭据与审计。连接失败时什么都不写。组织凭据型连接器的 `credential` 是组织凭据，个人型是创建者自己的。
+     * OAuth（A16，要求 `http.publicUrl`）：授权码连接器不做首次 listTools（首个成员连接后刷新），只存客户端；
+     * 客户端凭据连接器用安装时取到的组织 token listTools，存客户端与 token。
+     */
+    create(orgId: string, actorAccountId: string, input: CreateConnectorInput, actorTokenId?: string): Promise<{
+        connector: ConnectorDetail;
+        issues: ToolIssue[];
+    }>;
+    /**
+     * Checks a template update before anything is written (an org plugin upgrade): the endpoint
+     * against the connector's schema, and with `resetCredentials` the new credential's shape, or for
+     * OAuth the client setup (discovery, dynamic registration or the client credentials token; an
+     * outbound failure -> 502 `connector.connect_failed`). Writes nothing.
+     */
+    prepareTemplateUpdate(actorAccountId: string, connector: string, input: TemplateUpdateInput): Promise<PreparedTemplateUpdate>;
+    /**
+     * Applies a prepared template update in the caller's transaction (the caller holds the org row
+     * lock and checked the actor): the endpoint, auth and template version of the connector, the
+     * template's default policies (`template_tool_policies`) and the policies the org did not set
+     * (`policy_source` `template` or `derived`): a tool the new template names takes its policy
+     * (`template`), an unnamed `template` tool returns to the policy derived from its annotations,
+     * unnamed `derived` tools and the org's own (`admin`) stay (spec §10). Tool definitions are untouched (the next refresh takes the new endpoint through drift review). With `resetCredentials` the credentials are replaced.
+     * Audits `connector.template_applied`. Deleted / missing -> `connector.not_found`.
+     */
+    applyTemplateIn(t: Trx, orgId: string, connectorId: string, actorAccountId: string, p: PreparedTemplateUpdate, actorTokenId?: string): Promise<void>;
+    /**
+     * Previews a connector (Ruling A20, for the install wizard): after checking the connector, the
+     * endpoint (credential pattern check included) and the credential shape, reads the endpoint
+     * description with `connector.inspect` (auth hints, operations), and when it can authenticate
+     * (static credentials / a token from the client credentials flow) or auth is none, also lists the
+     * tools, builds keys from the slug and derives default policies and issues. Writes nothing (no
+     * rows, no audit); the OAuth authorization code flow lists no tools (no dynamic registration).
+     * Any outbound failure is 502 `connector.connect_failed`, the message holding only the
+     * connector's English explanation (redacted by the injected credentials) or the error class name.
+     * `customConnectors: deny` -> `catalog.custom_disabled`.
+     */
+    preview(orgId: string, input: PreviewConnectorInput): Promise<ConnectorPreview>;
+    private insertTools;
+    /** 读本组织未删除的连接器行；不存在 → `connector.not_found`。`lock` 时 FOR UPDATE。 */
+    private row;
+    private summary;
+    private detail;
+    /** 本组织未删除的连接器（按创建时间）。 */
+    list(orgId: string): Promise<ConnectorSummary[]>;
+    get(orgId: string, connectorId: string, viewerAccountId: string): Promise<ConnectorDetail>;
+    /** 改名、启停连接器、工具启停与默认策略、批量把无注解工具改为 allow（`connectors.manage`）。 */
+    update(orgId: string, connectorId: string, actorAccountId: string, patch: UpdateConnectorInput, actorTokenId?: string): Promise<ConnectorDetail>;
+    /** 软删除，并删除该连接器的全部凭据（`connectors.manage`）。 */
+    remove(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    /**
+     * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
+     * 审计 `connector.deleted`（`reason` 并进 detail）。已删除 / 不存在 → `connector.not_found`。
+     */
+    removeIn(t: Trx, orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string, reason?: string): Promise<void>;
+    /**
+     * 重新 listTools 并按漂移检测的规则比对写入（见 drift.ts）：新增 / 定义变化的工具待复核（旧定义保留供对比），
+     * 消失的工具停用；连接器从未拍过快照时首个快照直接启用。
+     * 组织凭据型连接器用组织凭据，个人型用发起人自己的凭据（缺 → `credential.missing`）。OAuth 连接器收到 401 时
+     * 在刷新锁内刷新 token 后重试一次。`trigger: "first_connect"`：OAuth 授权码连接器首个成员连接后由连接流程调用
+     * （A16），只要求 `connectors.use`。审计 `connector.tools_refreshed`（变化的工具名，不含定义）。
+     */
+    refresh(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string, opts?: {
+        trigger?: "first_connect";
+    }): Promise<{
+        connector: ConnectorDetail;
+        issues: ToolIssue[];
+        changes: DriftChanges;
+    }>;
+    /**
+     * 复核一个待复核的工具（`connectors.manage`，spec 7.3）。`approve`：采用待复核的新定义（若有）并启用，
+     * `reviewed_at` 记为现在；默认策略按新定义的注解重新推导，除非管理员设过（`policy_source = admin`）且来源没变。
+     * `reject`：停用，丢弃待复核的新定义、保留旧定义；从未复核过的工具被拒后 `reviewed_at` 仍为空（仍可再批准）。
+     * 工具不存在 → 404 `connector.tool_not_found`；不可复核（已复核且无待复核定义，或已消失）→ 409 `connector.tool_not_pending`；新定义不合规（如 key 不合法）不能通过 → `validation_failed`。
+     * 采用新定义即换了指纹：旧的「以后都允许」/「本会话都允许」授权按指纹比对自然失效（D8）。审计 `connector.tool_reviewed`。
+     */
+    reviewTool(orgId: string, connectorId: string, name: string, action: "approve" | "reject", actorAccountId: string, actorTokenId?: string): Promise<ConnectorDetail>;
+    /**
+     * 写凭据（组织凭据：`connectors.manage`；个人凭据：`connectors.use`，只写发起人自己的那一条）。
+     * 形状与归属不符 → `validation_failed`。审计只记类型与归属。
+     */
+    setCredential(orgId: string, connectorId: string, actorAccountId: string, ownership: "org" | "personal", value: unknown, actorTokenId?: string): Promise<void>;
+    /**
+     * 轮换 OAuth 客户端（Ruling A18，组织凭据接口，`connectors.manage`）：值为 `{ clientId, clientSecret }`。
+     * 客户端凭据连接器先用新客户端取一次 token 验证（失败 → 502 `connector.connect_failed`，什么都不改），再替换客户端并以
+     * 新 token 替换缓存的组织 token；授权码连接器只限手填 client，只替换客户端（成员的 token 保留，之后刷新若得到
+     * invalid_client 会作废）。审计只记类型与归属。
+     */
+    private rotateOAuthClient;
+    /** 删除发起人自己的个人凭据（`connectors.use`）；本来就没有也成功。 */
+    clearMyCredential(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+}