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

package/dist/tools/connectors.controller.js

@@ -10,13 +10,18 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { ConnectorAuthSchema } from "@capybara-hq/plugin-sdk";
 import { Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, Put } from "@nestjs/common";
 import { z } from "zod";
+import { orgIconScope, PluginIcons } from "../extensions/plugin-icons.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { can } from "../orgs/roles.js";
+import { ConnectorAccountPolicies, } from "./connector-account-policies.js";
+import { ConnectorGuideAckSchema, CredentialValue, MemberToolPoliciesBody, } from "./connectors.schemas.js";
 import { ConnectorsService, } from "./connectors.service.js";
 import { publicEndpoint } from "./endpoint.js";
+import { callbackUrl } from "./oauth/flow-paths.js";
 /**
  * 没有 `connectors.manage` 的读者只看到端点的公开部分（URL 不带 query、只有头名，见 endpoint.ts），
  * 也看不到工具的连接器数据（可能含服务器地址）。
@@ -34,10 +39,6 @@ function forViewer(org, c) {
     }
     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),
@@ -87,21 +88,67 @@ class ConnectorToolReviewBody extends createZodDto(ReviewBody, "ConnectorToolRev
 }
 class ConnectorCredentialBody extends createZodDto(CredentialValue, "ConnectorCredentialBody") {
 }
+class MemberToolPoliciesDto extends createZodDto(MemberToolPoliciesBody, "MemberToolPoliciesBody") {
+}
+class ConnectorGuideAckBody extends createZodDto(ConnectorGuideAckSchema, "ConnectorGuideAckBody") {
+}
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
  */
 let ConnectorsController = class ConnectorsController {
     connectors;
-    constructor(connectors) {
+    icons;
+    memberPolicies;
+    config;
+    constructor(connectors, icons, memberPolicies, config) {
         this.connectors = connectors;
+        this.icons = icons;
+        this.memberPolicies = memberPolicies;
+        this.config = config;
+    }
+    /**
+     * Each connector with `icon`: the icon of the plugin its template came from, on the org's catalog
+     * route (null for a custom connector, a plugin without an icon, or one the reader's catalog does
+     * not show: the share gate holds; maintainer decision 2026-11-09).
+     */
+    async withIcons(org, rows) {
+        const ids = rows.flatMap((r) => (r.catalogItemId === null ? [] : [r.catalogItemId]));
+        const urls = await this.icons.ofItems(ids, orgIconScope(org));
+        return rows.map((r) => ({
+            ...r,
+            icon: r.catalogItemId === null ? null : (urls.get(r.catalogItemId) ?? null),
+        }));
     }
     async list(org) {
-        return { connectors: (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a)) };
+        const list = (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a));
+        return { connectors: await this.withGuides(org, list) };
+    }
+    /** Adds the icon and the setup guide fields to connector views (one lookup each for all). */
+    async withGuides(org, views) {
+        const [withIcons, states] = await Promise.all([
+            this.withIcons(org, views),
+            this.connectors.guideStates(org, views.map((v) => v.id)),
+        ]);
+        return withIcons.map((v) => ({
+            ...v,
+            ...(states.get(v.id) ?? { setupGuide: null, guideDrift: null }),
+        }));
+    }
+    async withGuide(org, view) {
+        return (await this.withGuides(org, [view]))[0];
+    }
+    /**
+     * The connector kinds the org can create connectors of, each with the plugin providing it (the
+     * install wizard offers only these; an empty list means no connector extension is enabled).
+     */
+    async kinds(org) {
+        return { kinds: await this.connectors.kinds(org.orgId) };
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
-        return this.connectors.create(org.orgId, p.account.id, body, patTokenId(p));
+        const r = await this.connectors.create(org.orgId, p.account.id, body, patTokenId(p));
+        return { ...r, connector: await this.withGuide(org, r.connector) };
     }
     /**
      * 预览（安装向导）：读端点描述（认证提示、操作清单）并在能认证时列出工具，什么都不写。
@@ -113,15 +160,22 @@ let ConnectorsController = class ConnectorsController {
     }
     async get(principal, org, connectorId) {
         const p = requireUser(principal);
+        const view = forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id));
+        const page = await this.withGuide(org, view);
+        // The redirect URI to register at the authorization server, for those who manage connectors
+        // (the credentials tab shows it next to the OAuth client); null without `http.publicUrl`.
+        if (page.auth.type !== "oauth_code" || !can(org.role, "connectors.manage")) {
+            return { connector: page };
+        }
+        const publicUrl = this.config.get().http.publicUrl;
         return {
-            connector: forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id)),
+            connector: { ...page, oauthCallbackUrl: publicUrl ? callbackUrl(publicUrl) : null },
         };
     }
     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)),
-        };
+        const view = await this.connectors.update(org.orgId, connectorId, p.account.id, body, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
     }
     async remove(principal, org, connectorId) {
         const p = requireUser(principal);
@@ -129,14 +183,25 @@ let ConnectorsController = class ConnectorsController {
     }
     async refresh(principal, org, connectorId) {
         const p = requireUser(principal);
-        return this.connectors.refresh(org.orgId, connectorId, p.account.id, patTokenId(p));
+        const r = await this.connectors.refresh(org.orgId, connectorId, p.account.id, patTokenId(p));
+        return { ...r, connector: await this.withGuide(org, r.connector) };
     }
     /** 复核待复核的工具（漂移检测，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)),
-        };
+        const view = await this.connectors.reviewTool(org.orgId, connectorId, name, body.action, p.account.id, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
+    }
+    /**
+     * 「我已更新应用」: the org admin updated the third-party app to the connector template's current
+     * setup guide (`{ hash }` of the guide shown) -> 200 `{ connector }`; 409
+     * `connector.guide_changed` when the guide moved on since, 404 `catalog.guide_not_found` for a
+     * connector without a template guide.
+     */
+    async ackGuide(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        const view = await this.connectors.ackGuide({ orgId: org.orgId, role: org.role }, connectorId, body.hash, p.account.id, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
     }
     async setOrgCredential(principal, org, connectorId, body) {
         const p = requireUser(principal);
@@ -146,6 +211,26 @@ let ConnectorsController = class ConnectorsController {
         const p = requireUser(principal);
         await this.connectors.setCredential(org.orgId, connectorId, p.account.id, "personal", body, patTokenId(p));
     }
+    /**
+     * The caller's own tool policies for their own connection of a personal-credential connector
+     * (the card's 权限, decision 2026-11-09): each tool with the org default, the annotation default,
+     * the caller's setting and whether the org locked it. Only ever the caller's rows. A connector
+     * with one org credential -> 409 `connector.not_personal`.
+     */
+    async myToolPolicies(principal, org, connectorId) {
+        const p = requireUser(principal);
+        return { tools: await this.memberPolicies.read(org.orgId, connectorId, p.account.id) };
+    }
+    /**
+     * Sets (`allow` / `ask` / `deny`) or clears (null) the caller's own policies for some tools:
+     * `{ tools: { <name>: policy | null } }` -> the sheet again. Unknown tool -> 404
+     * `connector.tool_not_found`.
+     */
+    async setMyToolPolicies(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        await this.memberPolicies.set(org.orgId, connectorId, p.account.id, body.tools, patTokenId(p));
+        return { tools: await this.memberPolicies.read(org.orgId, connectorId, p.account.id) };
+    }
     async clearMyCredential(principal, org, connectorId) {
         const p = requireUser(principal);
         await this.connectors.clearMyCredential(org.orgId, connectorId, p.account.id, patTokenId(p));
@@ -156,6 +241,11 @@ __decorate([
     OrgAction("connectors.use"),
     __param(0, CurrentOrg())
 ], ConnectorsController.prototype, "list", null);
+__decorate([
+    Get("kinds"),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentOrg())
+], ConnectorsController.prototype, "kinds", null);
 __decorate([
     Post(),
     OrgAction("connectors.manage"),
@@ -212,6 +302,15 @@ __decorate([
     __param(3, Param("name")),
     __param(4, ZBody(ConnectorToolReviewBody))
 ], ConnectorsController.prototype, "review", null);
+__decorate([
+    Post(":connectorId/guide-ack"),
+    HttpCode(200),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, ZBody(ConnectorGuideAckBody))
+], ConnectorsController.prototype, "ackGuide", null);
 __decorate([
     Put(":connectorId/credentials/org"),
     HttpCode(204),
@@ -230,6 +329,21 @@ __decorate([
     __param(2, Param("connectorId")),
     __param(3, ZBody(ConnectorCredentialBody))
 ], ConnectorsController.prototype, "setMyCredential", null);
+__decorate([
+    Get(":connectorId/tool-policies/me"),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId"))
+], ConnectorsController.prototype, "myToolPolicies", null);
+__decorate([
+    Put(":connectorId/tool-policies/me"),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, ZBody(MemberToolPoliciesDto))
+], ConnectorsController.prototype, "setMyToolPolicies", null);
 __decorate([
     Delete(":connectorId/credentials/me"),
     HttpCode(204),
@@ -240,6 +354,9 @@ __decorate([
 ], ConnectorsController.prototype, "clearMyCredential", null);
 ConnectorsController = __decorate([
     Controller("api/v1/orgs/:orgId/connectors"),
-    __param(0, Inject(ConnectorsService))
+    __param(0, Inject(ConnectorsService)),
+    __param(1, Inject(PluginIcons)),
+    __param(2, Inject(ConnectorAccountPolicies)),
+    __param(3, Inject(KernelConfigService))
 ], ConnectorsController);
 export { ConnectorsController };

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

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/**
+ * A credential value: `Credentials.validate` checks its shape by auth method (values are never
+ * echoed); this only bounds its size.
+ */
+export declare const CredentialValue: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** 「我已更新应用」: the admin drift hash of the connector template guide the person was shown. */
+export declare const ConnectorGuideAckSchema: z.ZodObject<{
+    hash: z.ZodString;
+}, z.core.$strict>;
+/** `:connectorId` as the routes take it (`@Param`). */
+export declare const ConnectorPathParams: z.ZodObject<{
+    connectorId: z.ZodString;
+}, z.core.$strip>;
+export declare const CONNECTOR_ROUTES: readonly RouteSchemas[];
+/**
+ * `PUT …/connectors/:connectorId/tool-policies/me`: the caller's own policy per tool name (null
+ * clears it; decision 2026-11-09).
+ */
+export declare const MemberToolPoliciesBody: z.ZodObject<{
+    tools: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        deny: "deny";
+    }>>>;
+}, z.core.$strict>;

package/dist/tools/connectors.schemas.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+/**
+ * A credential value: `Credentials.validate` checks its shape by auth method (values are never
+ * echoed); this only bounds its size.
+ */
+export const CredentialValue = z
+    .record(z.string().max(100), z.unknown())
+    .refine((v) => JSON.stringify(v).length <= 16_384, { message: "Credential is too large" });
+/** 「我已更新应用」: the admin drift hash of the connector template guide the person was shown. */
+export const ConnectorGuideAckSchema = z
+    .object({ hash: z.string().regex(/^[0-9a-f]{64}$/) })
+    .strict();
+/** `:connectorId` as the routes take it (`@Param`). */
+export const ConnectorPathParams = z.object({ connectorId: z.string().min(1) });
+export const CONNECTOR_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/connectors" },
+    { route: "GET /api/v1/orgs/:orgId/connectors/:connectorId", params: ConnectorPathParams },
+    { route: "DELETE /api/v1/orgs/:orgId/connectors/:connectorId", params: ConnectorPathParams },
+    {
+        route: "POST /api/v1/orgs/:orgId/connectors/:connectorId/refresh",
+        params: ConnectorPathParams,
+    },
+];
+/**
+ * `PUT …/connectors/:connectorId/tool-policies/me`: the caller's own policy per tool name (null
+ * clears it; decision 2026-11-09).
+ */
+export const MemberToolPoliciesBody = z
+    .object({
+    tools: z
+        .record(z.string().min(1).max(200), z.enum(["allow", "ask", "deny"]).nullable())
+        .refine((v) => Object.keys(v).length <= 1000, { message: "Too many tools" }),
+})
+    .strict();

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

@@ -1,9 +1,12 @@
 import { type AuthHint, type ConnectorOperation, type ToolAnnotations } from "@capybara-hq/plugin-sdk";
+import { type ConnectionGuideState, PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
+import type { WriteActor } from "../identity/write-actor.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 { OrgLock } from "../orgs/org-lock.js";
+import type { OrgRole } from "../orgs/roles.js";
 import { type ConnectorAuth, type CredentialOwner, Credentials, type StaticSecret } from "./credentials.js";
 import { type DriftChanges, ToolDrift, type ToolIssue } from "./drift.js";
 import { type OAuthClientRecord, type OAuthTokenRecord } from "./oauth/tokens.js";
@@ -15,6 +18,8 @@ type ToolSource = "connector" | "resources";
 export interface ConnectorToolView {
     name: string;
     key: string;
+    /** The reviewed definition's display-only title (`ToolSpec.title`), or null. */
+    title: string | null;
     description: string;
     inputSchema: Record<string, unknown>;
     annotations: ToolAnnotations | null;
@@ -59,6 +64,13 @@ export interface ConnectorSummary {
     endpoint: unknown;
     auth: ConnectorAuth;
     status: "active" | "disabled";
+    /**
+     * The platform connector template it was made from (`connectors.platform_template_id`), null for
+     * a custom one: the web offers it for a pending connector of that template (ruling P4-7).
+     */
+    platformTemplateId: string | null;
+    /** The plugin (catalog item) its template came from (`connectors.catalog_item_id`), else null. */
+    catalogItemId: string | null;
     createdBy: string;
     createdAt: Date;
     updatedAt: Date;
@@ -79,7 +91,7 @@ export interface CreateConnectorInput {
     auth: ConnectorAuth;
     credential?: unknown;
     /**
-     * Install from an enterprise catalog connector template (T26, filled in by the catalog service,
+     * Install from a platform 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'`).
@@ -87,6 +99,17 @@ export interface CreateConnectorInput {
      * (`catalog.custom_disabled`).
      */
     template?: ConnectorTemplateRef | undefined;
+    /**
+     * The name and slug are chosen under the org lock (one more connector from a template, ruling
+     * P4-T6-10; not accepted over HTTP; `slug` must be absent): the first free of `name` (else
+     * `display`) with its derived slug, then `<display> 2` with `_2`, `3` with `_3`, … (a given
+     * `name` is kept, only its slug suffixed), among the org's live connectors and the installed
+     * plugins' names. Chosen after the outbound calls, so a race never repeats them.
+     */
+    slugDefault?: {
+        display: string;
+        name?: string | undefined;
+    } | undefined;
 }
 /** 连接器来自哪个目录条目的哪个模板。 */
 export interface ConnectorTemplateRef {
@@ -97,10 +120,16 @@ export interface ConnectorTemplateRef {
     defaultToolPolicies?: Record<string, ToolPolicy> | undefined;
     /** The item whose policy approves this install (a dependency's template: the installed plugin). */
     approvedBy?: string | undefined;
+    /**
+     * One more connector from a platform connector template (ruling P4-T6-8): the template must be
+     * on in the org, re-checked under the org lock (`component.off` / `component.not_found`).
+     */
+    mustBeOn?: boolean | 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
+ * A connector updated to another version of its catalog template (the platform plugin update fans
+ * a changed template out to every connector with its `platform_template_id`, ruling E2): 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`.
  */
@@ -186,11 +215,15 @@ export declare class ConnectorsService {
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     private readonly orgLock;
     readonly txHost: TransactionHost;
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    private readonly guides;
     constructor(kdb: KernelDb, registry: ToolRegistry, 
     /** Extension manifests (a slug may not take an extension's name). */
     extensions: Pick<ExtensionRegistry, "manifests">, credentials: Credentials, config: Pick<KernelConfigService, "get">, drift: ToolDrift, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock: Pick<OrgLock, "lockAndAuthorize">, txHost: TransactionHost);
+    orgLock: Pick<OrgLock, "lock" | "lockAndAuthorize">, txHost: TransactionHost, 
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    guides: Pick<PluginGuides, "templateAck" | "connectorStates">);
     /** The kernel-schema handle of the current context (its transaction, else the pool). */
     private get db();
     /**
@@ -199,6 +232,11 @@ export declare class ConnectorsService {
      */
     private parseEndpoint;
     private slugTaken;
+    /**
+     * The first free default name and slug ({@link CreateConnectorInput.slugDefault}), read in the
+     * caller's transaction under the org lock.
+     */
+    private freeName;
     private resolveSlug;
     /**
      * OAuth 连接器安装前的准备（A16）：授权码流按 `discovery` 取端点（MCP 发现或手填）、按 `client` 动态注册或用请求里
@@ -231,7 +269,7 @@ export declare class ConnectorsService {
     /** The org-locked, re-checked insert of {@link create} (the outbound checks ran before). */
     private createIn;
     /**
-     * Checks a template update before anything is written (an org plugin upgrade): the endpoint
+     * Checks a template update before anything is written (the platform plugin update): 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.
@@ -247,6 +285,16 @@ export declare class ConnectorsService {
      * Audits `connector.template_applied`. Deleted / missing -> `connector.not_found`.
      */
     applyTemplateIn(orgId: string, connectorId: string, actorAccountId: string, p: PreparedTemplateUpdate, actorTokenId?: string): Promise<void>;
+    /** Refuses a loaded kind whose extension is not enabled in the org (the same notion as {@link kinds}). */
+    private assertKindAvailable;
+    /**
+     * The connector kinds the org can create connectors of (the install wizard's protocol step): a
+     * kind is listed when its `connector@1` extension is loaded and enabled in the org.
+     */
+    kinds(orgId: string): Promise<{
+        kind: string;
+        plugin: string;
+    }[]>;
     /**
      * 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
@@ -264,18 +312,62 @@ export declare class ConnectorsService {
     private row;
     private summary;
     private detail;
-    /** 本组织未删除的连接器（按创建时间）。 */
+    /**
+     * The setup guide fields of the org's connectors (`setupGuide`, `guideDrift`; spec
+     * 2026-11-09-setup-guides-v2-design.md §9.3, §11): resolved through each connector's platform
+     * template to its item's guide for that template; custom connectors get nulls.
+     */
+    guideStates(org: {
+        orgId: string;
+        role: OrgRole;
+    }, connectorIds: string[]): Promise<Map<string, ConnectionGuideState>>;
+    /**
+     * 「我已更新应用」 for a connector made from a template: records the template's current guide as
+     * the one it is set up with. `hash` is the admin drift hash of the guide the person was shown;
+     * when the plugin moved on since, 409 `connector.guide_changed` (show the new guide first). A
+     * connector without a template guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
+     */
+    ackGuide(org: {
+        orgId: string;
+        role: OrgRole;
+    }, connectorId: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ConnectorDetail>;
+    /** The row and audit of {@link ackGuide}, in one transaction under the org lock. */
+    private ackIn;
+    /** The org's connectors that are not deleted (by creation time). */
     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>;
+    /**
+     * The org id of a live connector of a live org (the platform paths address a connector by its
+     * global id); else `connector.not_found`.
+     */
+    private liveOrgOf;
+    /**
+     * Disables or enables a connector on the platform's behalf (a super admin who need not be a
+     * member of the org; the caller checks the super admin): org row lock, the status update, audit
+     * `connector.updated` with `via: "platform"`. `auditDetail` (a Platform tool write's
+     * `viaAgent`) is merged into the detail; `via` stays `"platform"`.
+     */
+    setStatusAsPlatform(connectorId: string, status: "active" | "disabled", actor: WriteActor, auditDetail?: Record<string, unknown>): Promise<void>;
+    /**
+     * Deletes a connector on the platform's behalf (see {@link setStatusAsPlatform}): org row lock,
+     * then {@link removeIn} with `via: "platform"` in the audit detail (merged over `auditDetail`,
+     * a Platform tool write's `viaAgent`).
+     */
+    removeAsPlatform(connectorId: string, actor: WriteActor, auditDetail?: Record<string, unknown>): Promise<void>;
     /** 软删除，并删除该连接器的全部凭据（`connectors.manage`）。 */
-    remove(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    remove(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
     /**
      * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
      * 审计 `connector.deleted`（`reason` 并进 detail）。已删除 / 不存在 → `connector.not_found`。
      */
-    removeIn(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string, reason?: string): Promise<void>;
+    removeIn(orgId: string, connectorId: string, 
+    /** null: the kernel itself (the plugin scope sync uninstalling a plugin). */
+    actorAccountId: string | null, actorTokenId?: string, reason?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<void>;
     /**
      * 重新 listTools 并按漂移检测的规则比对写入（见 drift.ts）：新增 / 定义变化的工具待复核（旧定义保留供对比），
      * 消失的工具停用；连接器从未拍过快照时首个快照直接启用。
@@ -285,6 +377,7 @@ export declare class ConnectorsService {
      */
     refresh(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string, opts?: {
         trigger?: "first_connect";
+        auditDetail?: Record<string, unknown>;
     }): Promise<{
         connector: ConnectorDetail;
         issues: ToolIssue[];