@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/tools/builtins/web/search.js

@@ -0,0 +1,210 @@
+import { domainToASCII } from "node:url";
+import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { BUILTIN } from "../../builtin-names.js";
+import { webToolError } from "./errors.js";
+/** The extension point name (without the major) the provider is resolved from. */
+const POINT = "web-search";
+/**
+ * The fixed spec (web tools spec §3.1). No date and nothing per org or provider: `specHash` stays
+ * the same across days and providers, so remembered grants survive both and replays match the log.
+ * The date is the first line of every result instead.
+ */
+export const WEB_SEARCH_SPEC = {
+    name: BUILTIN.WebSearch,
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["query"],
+    description: "Search the web and get a list of results with title, URL and a short snippet. Use it for " +
+        "information newer than your training data, or to check whether something you know is still " +
+        "current. Then use WebFetch to read the pages you need. Do not use it for questions you can " +
+        "answer reliably without the web. Cite the sources you use.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                minLength: 2,
+                maxLength: 500,
+                description: "The search query.",
+            },
+            allowed_domains: {
+                type: "array",
+                items: { type: "string", minLength: 1, maxLength: 253 },
+                maxItems: 50,
+                description: "Only return results from these domains (hostnames such as example.com; subdomains " +
+                    "are included). Do not combine with blocked_domains.",
+            },
+            blocked_domains: {
+                type: "array",
+                items: { type: "string", minLength: 1, maxLength: 253 },
+                maxItems: 50,
+                description: "Never return results from these domains (hostnames such as example.com; subdomains " +
+                    "are included). Do not combine with allowed_domains.",
+            },
+        },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+};
+/** The last line of a result with entries (Claude Code tells the model to list its sources). */
+const CITE_LINE = "Cite the sources you use as markdown links in your answer.";
+/** Why the tool is unavailable in an org (web tools spec §3.4; English, actionable). */
+function unavailableText(reason) {
+    if (reason === "none") {
+        return "No web search provider is enabled in this organization; ask an org admin to enable one.";
+    }
+    return "Several web search providers are enabled and none is the default; ask an org admin to choose one in the organization settings.";
+}
+/**
+ * A domain entry as a bare lowercase ASCII hostname: tolerates a scheme, a path, a port, a leading
+ * `*.` / `.` and a trailing dot; a Unicode (IDN) name becomes its punycode form, as result hosts
+ * are (WHATWG URL parsing). Empty when nothing is left.
+ */
+function normalizeDomain(entry) {
+    let d = entry.trim().toLowerCase();
+    d = d.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    d = d.replace(/[/?#].*$/, "").replace(/:\d+$/, "");
+    d = d.replace(/^\*\./, "").replace(/^\.+/, "").replace(/\.+$/, "");
+    if (d === "")
+        return d;
+    // domainToASCII is "" for a name IDNA rejects: keep the entry as given (it matches no host)
+    return domainToASCII(d) || d;
+}
+/**
+ * A domain list normalized; undefined when absent or empty (no filter). A list whose entries all
+ * normalize to nothing stays an empty list, which no host matches.
+ */
+const normalizeDomains = (list) => list === undefined || list.length === 0
+    ? undefined
+    : [...new Set(list.map(normalizeDomain).filter((d) => d !== ""))];
+/** Whether `host` is `domain` or one of its subdomains. */
+const covers = (domain, host) => host === domain || host.endsWith(`.${domain}`);
+const oneLine = (s) => s.replace(/\s+/g, " ").trim();
+/**
+ * The provider's results the model may see (web tools spec §7.2): an absolute http(s) URL, a
+ * non-empty title, each URL once, within the domain lists, at most `max`. The kernel filters even
+ * when the provider honored the domain hints.
+ */
+function usable(results, allowed, blocked, max) {
+    const seen = new Set();
+    const out = [];
+    for (const r of results) {
+        if (out.length >= max)
+            break;
+        if (typeof r?.url !== "string" || typeof r.title !== "string")
+            continue;
+        const title = oneLine(r.title);
+        if (title === "")
+            continue;
+        let u;
+        try {
+            // no base: a relative URL throws
+            u = new URL(r.url.trim());
+        }
+        catch {
+            continue;
+        }
+        if (u.protocol !== "https:" && u.protocol !== "http:")
+            continue;
+        const host = u.hostname.toLowerCase().replace(/\.$/, "");
+        if (host === "")
+            continue;
+        if (allowed !== undefined && !allowed.some((d) => covers(d, host)))
+            continue;
+        if (blocked?.some((d) => covers(d, host)))
+            continue;
+        if (seen.has(u.href))
+            continue;
+        seen.add(u.href);
+        const date = typeof r.publishedAt === "string" ? /^\d{4}-\d{2}-\d{2}/.exec(r.publishedAt.trim()) : null;
+        const snippet = typeof r.snippet === "string" ? oneLine(r.snippet) : "";
+        out.push({
+            title,
+            url: u.href,
+            ...(date !== null && { date: date[0] }),
+            ...(snippet !== "" && { snippet }),
+        });
+    }
+    return out;
+}
+/** The model-visible result (web tools spec §3.1): the date line first, then the entries. */
+function resultText(day, entries) {
+    const head = `Search date: ${day} (UTC).`;
+    if (entries.length === 0)
+        return `${head}\n\nNo results.`;
+    const blocks = entries.map((e, i) => [
+        `${i + 1}. ${e.title}`,
+        `   URL: ${e.url}`,
+        ...(e.date !== undefined ? [`   Published: ${e.date}`] : []),
+        ...(e.snippet !== undefined ? [`   ${e.snippet}`] : []),
+    ].join("\n"));
+    return [head, ...blocks, CITE_LINE].join("\n\n");
+}
+/** The query in the display summary: one line, at most this many code points. */
+const DISPLAY_QUERY_MAX = 120;
+function displayQuery(query) {
+    const cps = [...oneLine(query)];
+    return cps.length > DISPLAY_QUERY_MAX
+        ? `${cps.slice(0, DISPLAY_QUERY_MAX - 1).join("")}…`
+        : cps.join("");
+}
+/**
+ * The builtin `WebSearch` (web tools spec §3.1): searches with the org's `web-search@1` provider
+ * (`ExtensionPointDefaults`, resolved per call and per step, never cached), asking it for
+ * `web.search.maxResults` results with the domain lists as hints and the org's config, then
+ * filters the results again. Default `ask`; unavailable when the org has no provider or several
+ * without a default.
+ */
+export function webSearchTool(deps) {
+    const now = deps.now ?? (() => new Date());
+    return {
+        spec: WEB_SEARCH_SPEC,
+        defaultPolicy: "ask",
+        async unavailable({ orgId }) {
+            const r = await deps.points.resolve(orgId, POINT);
+            return r.ok ? null : unavailableText(r.reason);
+        },
+        async run(input, ctx) {
+            const { query, allowed_domains, blocked_domains } = input;
+            if (allowed_domains !== undefined && blocked_domains !== undefined) {
+                throw new ToolError("Pass either allowed_domains or blocked_domains, not both; call WebSearch again with one of them.");
+            }
+            const allowed = normalizeDomains(allowed_domains);
+            const blocked = normalizeDomains(blocked_domains);
+            // the provider may have changed since the step resolved the tool: resolve again
+            const resolved = await deps.points.resolve(ctx.orgId, POINT);
+            if (!resolved.ok)
+                throw new ToolError(unavailableText(resolved.reason));
+            const max = deps.config.get().web.search.maxResults;
+            const day = now().toISOString().slice(0, 10);
+            let results;
+            try {
+                const out = await resolved.impl.search({
+                    query,
+                    ...(allowed !== undefined && allowed.length > 0 && { allowedDomains: allowed }),
+                    ...(blocked !== undefined && blocked.length > 0 && { blockedDomains: blocked }),
+                    maxResults: max,
+                    orgConfig: resolved.orgConfig,
+                    config: resolved.config,
+                    signal: ctx.signal,
+                });
+                results = Array.isArray(out?.results) ? out.results : [];
+            }
+            catch (e) {
+                webToolError(e, "search");
+            }
+            const entries = usable(results, allowed, blocked, max);
+            const q = displayQuery(query);
+            const n = entries.length;
+            return {
+                content: [{ type: "text", text: resultText(day, entries) }],
+                display: {
+                    summary: {
+                        zh: `搜索网页：${q}（${n} 条结果）`,
+                        en: `Searched the web: ${q} (${n} result${n === 1 ? "" : "s"})`,
+                    },
+                },
+            };
+        },
+    };
+}

package/dist/tools/builtins/web/url.d.ts

@@ -0,0 +1,17 @@
+/** The longest URL `WebFetch` accepts, in characters (Claude Code's limit; web tools spec §7.1). */
+export declare const MAX_FETCH_URL_CHARS = 2000;
+/** The outcome of {@link normalizeFetchUrl}: the URL to fetch, or a model-visible error. */
+export type FetchUrlCheck = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A `WebFetch` URL checked and normalized (web tools spec §7.1): absolute http(s), `http:`
+ * upgraded to `https:`, no user name or password, at most {@link MAX_FETCH_URL_CHARS} characters
+ * (before and after normalization), and a host that can name a public internet host. Pure, no DNS: a public name that resolves to a
+ * private address is the provider's to refuse. Errors are English and tell the model what to pass.
+ */
+export declare function normalizeFetchUrl(raw: string): FetchUrlCheck;

package/dist/tools/builtins/web/url.js

@@ -0,0 +1,43 @@
+import { isPublicHostname } from "@capybara-hq/plugin-sdk";
+/** The longest URL `WebFetch` accepts, in characters (Claude Code's limit; web tools spec §7.1). */
+export const MAX_FETCH_URL_CHARS = 2000;
+const fail = (error) => ({ ok: false, error });
+/**
+ * A `WebFetch` URL checked and normalized (web tools spec §7.1): absolute http(s), `http:`
+ * upgraded to `https:`, no user name or password, at most {@link MAX_FETCH_URL_CHARS} characters
+ * (before and after normalization), and a host that can name a public internet host. Pure, no DNS: a public name that resolves to a
+ * private address is the provider's to refuse. Errors are English and tell the model what to pass.
+ */
+export function normalizeFetchUrl(raw) {
+    const input = raw.trim();
+    // a cheap guard before parsing; the normalized URL is checked again below
+    if (input.length > MAX_FETCH_URL_CHARS) {
+        return fail(`Pass a URL of at most ${MAX_FETCH_URL_CHARS} characters.`);
+    }
+    let u;
+    try {
+        // no base: a relative URL throws
+        u = new URL(input);
+    }
+    catch {
+        return fail("Pass a full absolute URL, such as https://example.com/page.");
+    }
+    if (u.protocol !== "https:" && u.protocol !== "http:") {
+        return fail("Pass an https URL; only http and https URLs can be fetched.");
+    }
+    if (u.username !== "" || u.password !== "") {
+        return fail("Pass the URL without a user name or password.");
+    }
+    u.protocol = "https:";
+    // `u.hostname` is WHATWG-normalized (lowercased, IDNA, numeric IPv4 forms such as `0x7f.0.0.1`
+    // rewritten to dotted decimal, IPv6 in brackets), which is what isPublicHostname expects: never
+    // pass it a hand-parsed host.
+    if (!isPublicHostname(u.hostname)) {
+        return fail("Pass a full public https URL; this host is private or local.");
+    }
+    // the limit is on the URL as fetched: the upgrade, IDNA and percent-encoding can lengthen it
+    if (u.href.length > MAX_FETCH_URL_CHARS) {
+        return fail(`Pass a URL of at most ${MAX_FETCH_URL_CHARS} characters.`);
+    }
+    return { ok: true, url: u.href };
+}

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

@@ -174,6 +174,16 @@ export declare class ConnectorsController {
     list(org: OrgContext): Promise<{
         connectors: ConnectorSummary[];
     }>;
+    /**
+     * 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).
+     */
+    kinds(org: OrgContext): Promise<{
+        kinds: {
+            kind: string;
+            plugin: string;
+        }[];
+    }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
         connector: ConnectorDetail;
         issues: ToolIssue[];

package/dist/tools/connectors.controller.js

@@ -99,6 +99,13 @@ let ConnectorsController = class ConnectorsController {
     async list(org) {
         return { connectors: (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a)) };
     }
+    /**
+     * 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));
@@ -156,6 +163,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"),

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

@@ -15,6 +15,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 +61,11 @@ 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;
     createdBy: string;
     createdAt: Date;
     updatedAt: Date;
@@ -79,7 +86,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 +94,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 +115,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`.
  */
@@ -199,6 +223,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 +260,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 +276,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
@@ -275,7 +314,9 @@ export declare class ConnectorsService {
      * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
      * 审计 `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): Promise<void>;
     /**
      * 重新 listTools 并按漂移检测的规则比对写入（见 drift.ts）：新增 / 定义变化的工具待复核（旧定义保留供对比），
      * 消失的工具停用；连接器从未拍过快照时首个快照直接启用。

package/dist/tools/connectors.service.js

@@ -12,7 +12,8 @@ import { connectorToolKey, ToolError, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { z } from "zod";
-import { assertItemInstallable } from "../catalog/requests.service.js";
+import { connectorTemplateState } from "../catalog/component-state.js";
+import { assertItemInstallable } from "../catalog/request-rules.js";
 import { ApiError } from "../errors.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
@@ -142,6 +143,34 @@ let ConnectorsService = class ConnectorsService {
             .executeTakeFirst();
         return row !== undefined;
     }
+    /**
+     * The first free default name and slug ({@link CreateConnectorInput.slugDefault}), read in the
+     * caller's transaction under the org lock.
+     */
+    async freeName(t, orgId, d) {
+        const base = deriveSlug(d.name ?? d.display) ?? deriveSlug(d.display);
+        if (base === null) {
+            throw fail("slug", `Cannot derive a slug from the name; provide one. ${SLUG_RULE}`);
+        }
+        const taken = new Set((await t
+            .selectFrom("connectors")
+            .select("slug")
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .execute()).map((r) => r.slug));
+        for (const m of this.extensions.manifests())
+            taken.add(m.name);
+        for (let n = 1;; n++) {
+            const suffix = n === 1 ? "" : `_${n}`;
+            const slug = `${base.slice(0, 24 - suffix.length).replace(/_+$/, "")}${suffix}`;
+            if (!isValidSlug(slug) || taken.has(slug))
+                continue;
+            const nth = ` ${n}`;
+            const name = d.name ??
+                (n === 1 ? d.display : `${[...d.display].slice(0, 80 - nth.length).join("")}${nth}`);
+            return { name: [...name].slice(0, 80).join(""), slug };
+        }
+    }
     resolveSlug(input) {
         if (input.slug !== undefined) {
             if (!isValidSlug(input.slug))
@@ -253,7 +282,8 @@ let ConnectorsService = class ConnectorsService {
     checkCreateInput(actorAccountId, input) {
         const slug = this.resolveSlug(input);
         const endpoint = this.parseEndpoint(input.connector, input.endpoint);
-        if (this.extensions.manifests().some((m) => m.name === slug)) {
+        // a defaulted slug skips plugin names itself (`freeName`)
+        if (!input.slugDefault && this.extensions.manifests().some((m) => m.name === slug)) {
             throw fail("slug", `Slug "${slug}" is the name of an installed plugin; choose another`);
         }
         const auth = input.auth;
@@ -311,21 +341,21 @@ let ConnectorsService = class ConnectorsService {
         // 自建被禁止时先拒绝（事务里再复核一次）：不该为此触发外连
         if (!input.template)
             await assertCustomAllowed(this.db, "customConnectors");
+        await this.assertKindAvailable(orgId, input.connector);
         const { slug, endpoint, owner, secret } = this.checkCreateInput(actorAccountId, input);
         const id = randomUUID();
         const auth = input.auth;
         const publicUrl = this.config.get().http.publicUrl;
-        // 先做不需要连接的检查：冲突的 slug 不该触发一次外连
-        if (await this.slugTaken(this.db, orgId, slug)) {
+        // 先做不需要连接的检查：冲突的 slug 不该触发一次外连 (a defaulted slug is chosen under the lock)
+        if (!input.slugDefault && (await this.slugTaken(this.db, orgId, slug))) {
             throw new ApiError("connector.slug_taken", "Connector slug is already taken");
         }
         const oauth = isOAuth(auth)
             ? await this.prepareOAuth(auth, endpoint, input.credential, publicUrl)
             : undefined;
-        let rows = [];
-        let issues = [];
+        let listed;
         if (auth.type !== "oauth_code") {
-            const listed = await this.drift.listTools(input.connector, endpoint, async () => {
+            listed = await this.drift.listTools(input.connector, endpoint, async () => {
                 if (auth.type === "none")
                     return { headers: {} };
                 if (oauth?.tokens) {
@@ -335,7 +365,6 @@ let ConnectorsService = class ConnectorsService {
                     throw new CredentialMissing(id, auth.ownership);
                 return this.credentials.injectionFor(id, auth, secret);
             }, { orgId, slug });
-            ({ rows, issues } = snapshot(slug, listed.specs, listed.resources));
         }
         return this.createIn(orgId, actorAccountId, input, actorTokenId, {
             id,
@@ -344,13 +373,12 @@ let ConnectorsService = class ConnectorsService {
             owner,
             secret,
             oauth,
-            rows,
-            issues,
+            listed,
         });
     }
     /** The org-locked, re-checked insert of {@link create} (the outbound checks ran before). */
     async createIn(orgId, actorAccountId, input, actorTokenId, c) {
-        const { id, slug, endpoint, owner, secret, oauth, rows, issues } = c;
+        const { id, endpoint, owner, secret, oauth } = c;
         const auth = input.auth;
         const t = this.db;
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "connectors.manage");
@@ -359,22 +387,53 @@ let ConnectorsService = class ConnectorsService {
         }
         else
             await assertCustomAllowed(t, "customConnectors");
-        if (await this.slugTaken(t, orgId, slug)) {
+        let slug = c.slug;
+        let name = input.name;
+        if (input.slugDefault)
+            ({ slug, name } = await this.freeName(t, orgId, input.slugDefault));
+        else if (await this.slugTaken(t, orgId, slug)) {
             throw new ApiError("connector.slug_taken", "Connector slug is already taken");
         }
+        // the snapshot's keys name the final slug
+        const { rows, issues } = c.listed === undefined
+            ? { rows: [], issues: [] }
+            : snapshot(slug, c.listed.specs, c.listed.resources);
+        // A connector made from a platform connector template stays linked to it (ruling E2)
+        const tpl = input.template;
+        const platformTemplate = tpl?.templateId !== undefined
+            ? await t
+                .selectFrom("platform_connector_templates")
+                .select("id")
+                .where("catalog_item_id", "=", tpl.itemId)
+                .where("template_id", "=", tpl.templateId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst()
+            : undefined;
+        if (tpl?.mustBeOn) {
+            const state = platformTemplate === undefined
+                ? "absent"
+                : await connectorTemplateState(t, orgId, platformTemplate.id);
+            if (state === "absent") {
+                throw new ApiError("component.not_found", "The connector template does not exist or is not available in this organization");
+            }
+            if (state === "off") {
+                throw new ApiError("component.off", "This connector template is off in this organization; switch it (or its plugin) on first");
+            }
+        }
         await t
             .insertInto("connectors")
             .values({
             id,
             org_id: orgId,
             slug,
-            name: input.name,
+            name,
             connector: input.connector,
             endpoint: JSON.stringify(endpoint),
             auth: JSON.stringify(auth),
             created_by: actorAccountId,
             catalog_item_id: input.template?.itemId ?? null,
             catalog_version: input.template?.version ?? null,
+            platform_template_id: platformTemplate?.id ?? null,
             // 授权码连接器安装时没有快照：模板的默认策略留到首个快照时应用
             template_tool_policies: input.template?.defaultToolPolicies
                 ? JSON.stringify(input.template.defaultToolPolicies)
@@ -418,7 +477,7 @@ let ConnectorsService = class ConnectorsService {
         return { connector: await this.detail(t, orgId, id, actorAccountId), issues };
     }
     /**
-     * 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.
@@ -534,6 +593,21 @@ let ConnectorsService = class ConnectorsService {
             },
         });
     }
+    /** Refuses a loaded kind whose extension is not enabled in the org (the same notion as {@link kinds}). */
+    async assertKindAvailable(orgId, kind) {
+        if (!this.registry.findConnector(kind))
+            return; // unknown kinds fail in parseEndpoint
+        if (!(await this.registry.connectorKindAvailable(orgId, kind))) {
+            throw new ApiError("connector.kind_unavailable", `Connector kind "${kind}" is not enabled for this organization; enable its plugin first`);
+        }
+    }
+    /**
+     * 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) {
+        return this.registry.connectorKindsFor(orgId);
+    }
     /**
      * 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
@@ -548,6 +622,7 @@ let ConnectorsService = class ConnectorsService {
     async preview(orgId, input) {
         // 部署禁止组织自建连接器时也不替组织去连任意端点（目录安装不走预览）
         await assertCustomAllowed(this.db, "customConnectors");
+        await this.assertKindAvailable(orgId, input.connector);
         const endpoint = this.parseEndpoint(input.connector, input.endpoint);
         const connector = this.registry.findConnector(input.connector);
         if (!connector)
@@ -684,6 +759,7 @@ let ConnectorsService = class ConnectorsService {
             endpoint: endpointView(r.endpoint),
             auth: r.auth,
             status: r.status,
+            platformTemplateId: r.platform_template_id ?? null,
             createdBy: r.created_by,
             createdAt: r.created_at,
             updatedAt: r.updated_at,
@@ -721,6 +797,7 @@ let ConnectorsService = class ConnectorsService {
                 return {
                     name: t.name,
                     key: connectorToolKey(r.slug, t.name),
+                    title: typeof spec.title === "string" ? spec.title : null,
                     description: spec.description,
                     inputSchema: spec.inputSchema,
                     annotations: spec.annotations ?? null,
@@ -891,7 +968,9 @@ let ConnectorsService = class ConnectorsService {
      * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
      * 审计 `connector.deleted`（`reason` 并进 detail）。已删除 / 不存在 → `connector.not_found`。
      */
-    async removeIn(orgId, connectorId, actorAccountId, actorTokenId, reason) {
+    async removeIn(orgId, connectorId, 
+    /** null: the kernel itself (the plugin scope sync uninstalling a plugin). */
+    actorAccountId, actorTokenId, reason) {
         const t = this.db;
         const app = await this.row(t, orgId, connectorId, true);
         await t

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[];
+    }>;
+}