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

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/connector-account-policies.d.ts

@@ -0,0 +1,51 @@
+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 ToolPolicy } from "./registry.js";
+/**
+ * Why a member cannot set a tool's policy: the org switched the tool off (or it is not offered:
+ * pending review, gone), or the org set its default to deny. Either way it stays denied.
+ */
+export type MemberPolicyLock = "disabled" | "org_deny";
+/** One tool on the member's 权限 sheet (`GET …/connectors/:id/tool-policies/me`). */
+export interface MemberToolPolicyView {
+    name: string;
+    key: string;
+    title: string | null;
+    description: string;
+    /** The org's default for the tool (`connector_tools.default_policy`): what applies without a setting. */
+    defaultPolicy: ToolPolicy;
+    /** What the tool's annotations alone give (`readOnlyHint: true` allows, anything else asks). */
+    annotationPolicy: "allow" | "ask";
+    /** The member's own setting, null without one. */
+    policy: ToolPolicy | null;
+    /** Locked by the org: the member's setting does not apply, the tool is denied. */
+    locked: MemberPolicyLock | null;
+}
+/** Whether a connector's credential is per member: its calls are made with the member's connection. */
+export declare const personalAuth: (auth: unknown) => boolean;
+/**
+ * A member's own tool policies for their own connection of a personal-credential connector
+ * (maintainer decision 2026-11-09, the connector card's 权限). They apply to every agent the
+ * member uses; an agent's tool policy overrides them; a tool the org switched off or set to deny
+ * stays denied (`tools/policy.ts` `connectorPolicy`). Only the account itself reads or writes its
+ * rows: the routes take the account from the session, never from the request.
+ */
+export declare class ConnectorAccountPolicies {
+    private readonly kdb;
+    private readonly orgLock;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, orgLock: OrgLock, txHost: TransactionHost);
+    /** The kernel-schema handle of the current context (its transaction, else the pool). */
+    private get db();
+    /** The connector's tools with the account's settings; not personal -> 409 `connector.not_personal`. */
+    read(orgId: string, connectorId: string, accountId: string): Promise<MemberToolPolicyView[]>;
+    /**
+     * Sets (a policy) or clears (null) the account's policies for some of the connector's tools;
+     * an unknown tool -> 404 `connector.tool_not_found`. Locked tools may hold a setting: it does not
+     * apply while the lock lasts. Audits `connector.member_policies_changed`.
+     */
+    set(orgId: string, connectorId: string, accountId: string, changes: Record<string, ToolPolicy | null>, actorTokenId?: string): Promise<void>;
+    /** The org's live personal-credential connector, else 404 / 409. */
+    private connector;
+}

package/dist/tools/connector-account-policies.js

@@ -0,0 +1,165 @@
+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 } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { policyFromAnnotations } from "./registry.js";
+/** Whether a connector's credential is per member: its calls are made with the member's connection. */
+export const personalAuth = (auth) => {
+    const a = auth;
+    return a !== null && a.type !== "none" && a.ownership === "personal";
+};
+const notPersonal = () => new ApiError("connector.not_personal", "This connector uses one credential for the whole organization; only a connector each member connects to with their own credential has per-member tool policies");
+const notFound = () => new ApiError("connector.not_found", "Connector not found");
+/**
+ * A member's own tool policies for their own connection of a personal-credential connector
+ * (maintainer decision 2026-11-09, the connector card's 权限). They apply to every agent the
+ * member uses; an agent's tool policy overrides them; a tool the org switched off or set to deny
+ * stays denied (`tools/policy.ts` `connectorPolicy`). Only the account itself reads or writes its
+ * rows: the routes take the account from the session, never from the request.
+ */
+let ConnectorAccountPolicies = class ConnectorAccountPolicies {
+    kdb;
+    orgLock;
+    txHost;
+    constructor(kdb, orgLock, txHost) {
+        this.kdb = kdb;
+        this.orgLock = orgLock;
+        this.txHost = txHost;
+    }
+    /** The kernel-schema handle of the current context (its transaction, else the pool). */
+    get db() {
+        return this.kdb.db;
+    }
+    /** The connector's tools with the account's settings; not personal -> 409 `connector.not_personal`. */
+    async read(orgId, connectorId, accountId) {
+        const c = await this.connector(orgId, connectorId);
+        const tools = await this.db
+            .selectFrom("connector_tools")
+            .select(["name", "spec", "status", "default_policy", "missing_since"])
+            .where("connector_id", "=", connectorId)
+            .orderBy("name")
+            .execute();
+        const mine = new Map((await this.db
+            .selectFrom("connector_tool_account_policies")
+            .select(["tool_name", "policy"])
+            .where("connector_id", "=", connectorId)
+            .where("account_id", "=", accountId)
+            .execute()).map((r) => [r.tool_name, r.policy]));
+        return tools.map((t) => {
+            const spec = t.spec;
+            const locked = t.status !== "enabled" || t.missing_since !== null
+                ? "disabled"
+                : t.default_policy === "deny"
+                    ? "org_deny"
+                    : null;
+            return {
+                name: t.name,
+                key: connectorToolKey(c.slug, t.name),
+                title: typeof spec.title === "string" ? spec.title : null,
+                description: spec.description,
+                defaultPolicy: t.default_policy,
+                annotationPolicy: policyFromAnnotations(spec.annotations),
+                policy: mine.get(t.name) ?? null,
+                locked,
+            };
+        });
+    }
+    /**
+     * Sets (a policy) or clears (null) the account's policies for some of the connector's tools;
+     * an unknown tool -> 404 `connector.tool_not_found`. Locked tools may hold a setting: it does not
+     * apply while the lock lasts. Audits `connector.member_policies_changed`.
+     */
+    async set(orgId, connectorId, accountId, changes, actorTokenId) {
+        await this.orgLock.lockAndAuthorize(orgId, accountId, "connectors.use");
+        await this.connector(orgId, connectorId);
+        const names = Object.keys(changes);
+        if (names.length === 0)
+            return;
+        const known = new Set((await this.db
+            .selectFrom("connector_tools")
+            .select("name")
+            .where("connector_id", "=", connectorId)
+            .where("name", "in", names)
+            .execute()).map((r) => r.name));
+        const unknown = names.find((n) => !known.has(n));
+        if (unknown !== undefined) {
+            throw new ApiError("connector.tool_not_found", `No tool ${unknown} in this connector`);
+        }
+        const cleared = names.filter((n) => changes[n] === null);
+        if (cleared.length > 0) {
+            await this.db
+                .deleteFrom("connector_tool_account_policies")
+                .where("connector_id", "=", connectorId)
+                .where("account_id", "=", accountId)
+                .where("tool_name", "in", cleared)
+                .execute();
+        }
+        const set = names.flatMap((n) => {
+            const p = changes[n];
+            return p === null || p === undefined ? [] : [{ name: n, policy: p }];
+        });
+        if (set.length > 0) {
+            await this.db
+                .insertInto("connector_tool_account_policies")
+                .values(set.map((x) => ({
+                org_id: orgId,
+                connector_id: connectorId,
+                account_id: accountId,
+                tool_name: x.name,
+                policy: x.policy,
+            })))
+                .onConflict((oc) => oc.columns(["connector_id", "account_id", "tool_name"]).doUpdateSet({
+                policy: (eb) => eb.ref("excluded.policy"),
+                updated_at: sql `now()`,
+            }))
+                .execute();
+        }
+        await audit(this.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "connector.member_policies_changed",
+            target: connectorId,
+            detail: { tools: changes },
+        });
+    }
+    /** The org's live personal-credential connector, else 404 / 409. */
+    async connector(orgId, connectorId) {
+        const c = await this.db
+            .selectFrom("connectors")
+            .select(["slug", "auth"])
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!c)
+            throw notFound();
+        if (!personalAuth(c.auth))
+            throw notPersonal();
+        return { slug: c.slug };
+    }
+};
+__decorate([
+    Transactional()
+], ConnectorAccountPolicies.prototype, "set", null);
+ConnectorAccountPolicies = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(OrgLock)),
+    __param(2, Inject(TransactionHost))
+], ConnectorAccountPolicies);
+export { ConnectorAccountPolicies };

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

@@ -1,9 +1,12 @@
 import { z } from "zod";
+import type { ConnectionGuideState } from "../extensions/plugin-guides.js";
+import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { ConnectorAccountPolicies, type MemberToolPolicyView } from "./connector-account-policies.js";
+import { ConnectorGuideAckSchema, CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
 import { type ConnectorDetail, type ConnectorPreview, type ConnectorSummary, ConnectorsService, type ToolIssue } from "./connectors.service.js";
-/** 凭据值：形状由 `Credentials.validate` 按认证方式校验（不回显值）；这里只限大小。 */
-export declare const CredentialValue: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 declare const CreateBody: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
@@ -59,6 +62,7 @@ declare const CreateBody: z.ZodObject<{
             client_secret_basic: "client_secret_basic";
             client_secret_post: "client_secret_post";
         }>>;
+        tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"oauth_client">;
         ownership: z.ZodLiteral<"org">;
@@ -68,6 +72,7 @@ declare const CreateBody: z.ZodObject<{
             client_secret_basic: "client_secret_basic";
             client_secret_post: "client_secret_post";
         }>>;
+        tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>], "type">;
     credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;
@@ -127,6 +132,7 @@ declare const PreviewBody: z.ZodObject<{
             client_secret_basic: "client_secret_basic";
             client_secret_post: "client_secret_post";
         }>>;
+        tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"oauth_client">;
         ownership: z.ZodLiteral<"org">;
@@ -136,6 +142,7 @@ declare const PreviewBody: z.ZodObject<{
             client_secret_basic: "client_secret_basic";
             client_secret_post: "client_secret_post";
         }>>;
+        tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>], "type">>;
     credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;
@@ -164,18 +171,50 @@ declare const UpdateBody: z.ZodObject<{
     }, z.core.$strict>>>;
     allowUnannotated: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+/**
+ * A connector as the org's pages show it: with its plugin's icon (`icon`, see `withIcons`), its
+ * template's setup guide and the drift since it was set up (`setupGuide`, `guideDrift`; spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3, §11).
+ */
+export type ConnectorPage<T extends ConnectorSummary = ConnectorDetail> = T & ConnectionGuideState & {
+    icon: string | null;
+    /** The one-connector read of an `oauth_code` connector, for managers: its redirect URI. */
+    oauthCallbackUrl?: string | null;
+};
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
  */
 export declare class ConnectorsController {
     private readonly connectors;
-    constructor(connectors: ConnectorsService);
+    private readonly icons;
+    private readonly memberPolicies;
+    private readonly config;
+    constructor(connectors: ConnectorsService, icons: PluginIcons, memberPolicies: ConnectorAccountPolicies, config: Pick<KernelConfigService, "get">);
+    /**
+     * 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).
+     */
+    private withIcons;
     list(org: OrgContext): Promise<{
-        connectors: ConnectorSummary[];
+        connectors: ConnectorPage<ConnectorSummary>[];
+    }>;
+    /** Adds the icon and the setup guide fields to connector views (one lookup each for all). */
+    private withGuides;
+    private withGuide;
+    /**
+     * 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;
+        connector: ConnectorPage;
         issues: ToolIssue[];
     }>;
     /**
@@ -184,14 +223,14 @@ export declare class ConnectorsController {
      */
     preview(principal: Principal, org: OrgContext, body: z.infer<typeof PreviewBody>): Promise<ConnectorPreview>;
     get(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
     }>;
     update(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof UpdateBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
     }>;
     remove(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
     refresh(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
         issues: ToolIssue[];
         changes: {
             added: string[];
@@ -201,10 +240,36 @@ export declare class ConnectorsController {
     }>;
     /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
     review(principal: Principal, org: OrgContext, connectorId: string, name: string, body: z.infer<typeof ReviewBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
+    }>;
+    /**
+     * 「我已更新应用」: 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.
+     */
+    ackGuide(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof ConnectorGuideAckSchema>): Promise<{
+        connector: ConnectorPage;
     }>;
     setOrgCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;
     setMyCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;
+    /**
+     * 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`.
+     */
+    myToolPolicies(principal: Principal, org: OrgContext, connectorId: string): Promise<{
+        tools: MemberToolPolicyView[];
+    }>;
+    /**
+     * 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`.
+     */
+    setMyToolPolicies(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof MemberToolPoliciesBody>): Promise<{
+        tools: MemberToolPolicyView[];
+    }>;
     clearMyCredential(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
 }
 export {};