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

package/dist/tools/connector-content.js

@@ -0,0 +1,267 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { CredentialMissing } from "./credentials.js";
+import { renderResult } from "./outputs.js";
+import { redactDeep, redactorFor } from "./redact.js";
+import { READ_RESOURCE } from "./resources.js";
+/**
+ * 用户直接使用连接器内容（D4，仿 Claude Code）：`/` 斜杠命令（MCP prompts）与 `@` 资源引用。
+ *
+ * 与工具调用不同，这些操作由用户本人发起、不经模型：用发起人的凭据（组织凭据 / 本人的个人凭据）打开连接器会话，
+ * 结果按本次注入的凭据打码（同 Review Focus 3）。不经工具策略与审批（用户自己在用），只要求 `connectors.use`、
+ * 连接器为 active；熔断打开的连接器直接跳过 / 报错，不计入熔断（列表请求是界面行为，不应让工具调用熔断）。
+ * 会话按次打开、用完关闭，不缓存（多副本）。
+ */
+/** 列表请求里每个连接器的超时上限（毫秒；取它与 `tools.timeoutMs` 的较小值）。 */
+const LIST_TIMEOUT_MS = 10_000;
+/** 一次列出的资源最多条数。 */
+const MAX_RESOURCES = 500;
+/** 渲染后的提示文本上限（与消息正文上限一致）。 */
+const MAX_PROMPT_CHARS = 100_000;
+/** 每个附件的正文上限（字符）。 */
+export const MAX_ATTACHMENT_CHARS = 50_000;
+/** 一条消息最多附件数。 */
+export const MAX_ATTACHMENTS = 5;
+/** 解析一条消息全部附件的总时限上限（毫秒；取它与 `tools.timeoutMs` 的较小值，附件并行读取）。 */
+const ATTACHMENTS_TIMEOUT_MS = 30_000;
+/** 错误说明里带的上游错误消息最多字符数。 */
+const MAX_DETAIL = 500;
+const errName = (e) => e instanceof Error && typeof e.name === "string" && e.name !== "" ? e.name : "Error";
+export class ConnectorContent {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    async activeConnectors(orgId) {
+        return this.d.db
+            .selectFrom("connectors")
+            .select(["id", "slug", "name", "connector", "endpoint", "auth"])
+            .where("org_id", "=", orgId)
+            .where("status", "=", "active")
+            .where("deleted_at", "is", null)
+            .orderBy("created_at")
+            .orderBy("id")
+            .execute();
+    }
+    async connectorRow(orgId, connectorId) {
+        const r = await this.d.db
+            .selectFrom("connectors")
+            .select(["id", "slug", "name", "connector", "endpoint", "auth"])
+            .where("org_id", "=", orgId)
+            .where("id", "=", connectorId)
+            .where("status", "=", "active")
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!r)
+            throw new ApiError("connector.not_found", "Connector not found");
+        return r;
+    }
+    /**
+     * 读取资源受管理员对该连接器 `read_resource` 工具（`source = 'resources'`）的启停约束（Ruling A23）：
+     * 返回其中该工具为 enabled 的连接器 id。
+     */
+    async resourcesEnabled(connectorIds) {
+        if (connectorIds.length === 0)
+            return new Set();
+        const rows = await this.d.db
+            .selectFrom("connector_tools")
+            .select("connector_id")
+            .where("connector_id", "in", connectorIds)
+            .where("source", "=", "resources")
+            .where("name", "=", READ_RESOURCE)
+            .where("status", "=", "enabled")
+            .execute();
+        return new Set(rows.map((r) => r.connector_id));
+    }
+    /**
+     * 以 `accountId` 的凭据打开连接器会话执行 `work`，结果按本次注入的凭据打码，会话无论成败都关闭。
+     * 缺凭据 → `credential.missing`；熔断打开、连接 / 远端失败 → 502 `connector.connect_failed`（消息打码、限长）。
+     * `work` 返回 undefined 表示该连接器不支持这项能力。
+     */
+    async withSession(orgId, app, accountId, timeoutMs, work) {
+        const connector = this.d.registry.findConnector(app.connector);
+        if (!connector) {
+            throw new ApiError("connector.connect_failed", `The connector ${app.connector} is not installed`);
+        }
+        const breaker = await this.d.breaker.check(orgId, app.id);
+        if (breaker.open) {
+            throw new ApiError("connector.connect_failed", `The connector is temporarily unavailable; retry in ${breaker.retryAfterSeconds}s`);
+        }
+        const auth = app.auth;
+        const injected = [];
+        let cached;
+        const getAuth = () => {
+            cached ??= this.d.credentials.injection(orgId, app.id, auth, accountId).then((inj) => {
+                injected.push(inj);
+                return inj;
+            });
+            return cached;
+        };
+        const redact = () => redactorFor(injected);
+        let session;
+        try {
+            await getAuth(); // 缺凭据（CredentialMissing）在打开会话之前就确定
+            session = await connector.open({
+                endpoint: app.endpoint,
+                auth: getAuth,
+                onUnauthorized: async () => {
+                    const stale = injected.at(-1);
+                    cached = undefined;
+                    await this.d.credentials.onUnauthorized(orgId, app.id, auth, accountId, stale);
+                },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            return redactDeep(await work(session), redact());
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                throw e;
+            this.d.log.warn("connector content request failed", { orgId, connectorId: app.id, err: e });
+            const detail = e instanceof ToolError
+                ? `: ${redact()(e.message).slice(0, MAX_DETAIL)}`
+                : ` (${errName(e)})`;
+            throw new ApiError("connector.connect_failed", `The connector request failed${detail}`);
+        }
+        finally {
+            await session?.close().catch((err) => {
+                this.d.log.warn("connector session close failed", { orgId, connectorId: app.id, err });
+            });
+        }
+    }
+    /** 对每个 active 连接器并行执行 `work`；缺凭据 / 失败的连接器进 `unavailable`，不支持的（undefined）跳过。 */
+    async acrossConnectors(orgId, accountId, work, only) {
+        const all = await this.activeConnectors(orgId);
+        const apps = only ? await only(all) : all;
+        const timeoutMs = Math.min(this.d.config().tools.timeoutMs, LIST_TIMEOUT_MS);
+        const results = await Promise.all(apps.map(async (app) => {
+            try {
+                return {
+                    app,
+                    items: await this.withSession(orgId, app, accountId, timeoutMs, (s) => work(s, app)),
+                };
+            }
+            catch (e) {
+                const reason = e instanceof CredentialMissing ? "not_connected" : "failed";
+                return { app, unavailable: { connectorId: app.id, connectorName: app.name, reason } };
+            }
+        }));
+        const items = [];
+        const unavailable = [];
+        for (const r of results) {
+            if ("unavailable" in r)
+                unavailable.push(r.unavailable);
+            else if (r.items)
+                items.push(...r.items);
+        }
+        return { items, unavailable };
+    }
+    /** 发起人可用的全部提示模板（按连接器创建顺序，连接器内按远端顺序）。 */
+    async listPrompts(orgId, accountId) {
+        const { items, unavailable } = await this.acrossConnectors(orgId, accountId, async (s, app) => {
+            if (!s.listPrompts)
+                return undefined;
+            return (await s.listPrompts()).map((p) => ({
+                connectorId: app.id,
+                connectorSlug: app.slug,
+                connectorName: app.name,
+                name: p.name,
+                ...(p.title !== undefined && { title: p.title }),
+                ...(p.description !== undefined && { description: p.description }),
+                arguments: p.arguments,
+            }));
+        });
+        return { prompts: items, unavailable };
+    }
+    /**
+     * 渲染一个提示模板为文本（供用户放进输入框再发送）：各消息的文本按顺序以空行连接，assistant 消息加
+     * `Assistant:` 前缀；非文本内容给类型说明。连接器不支持 prompts → 404 `connector.not_found`。
+     */
+    async getPrompt(orgId, connectorId, name, args, accountId) {
+        const app = await this.connectorRow(orgId, connectorId);
+        const rendered = await this.withSession(orgId, app, accountId, this.d.config().tools.timeoutMs, async (s) => (s.getPrompt ? s.getPrompt(name, args) : undefined));
+        if (!rendered)
+            throw new ApiError("connector.not_found", "This connector does not provide prompts");
+        let text = rendered.messages
+            .map((m) => {
+            const t = renderResult({ content: m.content }).text;
+            return m.role === "assistant" ? `Assistant: ${t}` : t;
+        })
+            .join("\n\n");
+        if (text.length > MAX_PROMPT_CHARS)
+            text = text.slice(0, MAX_PROMPT_CHARS);
+        return { text };
+    }
+    /** 发起人可用的资源；`query` 按名称 / URI / 描述的子串过滤（不区分大小写），最多 {@link MAX_RESOURCES} 条。 */
+    async listResources(orgId, accountId, query) {
+        const q = query?.trim().toLowerCase() ?? "";
+        const { items, unavailable } = await this.acrossConnectors(orgId, accountId, async (s, app) => {
+            if (!s.listResources)
+                return undefined;
+            return (await s.listResources())
+                .filter((r) => q === "" ||
+                [r.name, r.uri, r.description ?? ""].some((v) => v.toLowerCase().includes(q)))
+                .map((r) => ({
+                connectorId: app.id,
+                connectorSlug: app.slug,
+                connectorName: app.name,
+                uri: r.uri,
+                name: r.name,
+                ...(r.description !== undefined && { description: r.description }),
+                ...(r.mimeType !== undefined && { mimeType: r.mimeType }),
+            }));
+        }, 
+        // 管理员停用了读取资源的连接器不列出（也不打开会话）
+        async (apps) => {
+            const enabled = await this.resourcesEnabled(apps.map((a) => a.id));
+            return apps.filter((a) => enabled.has(a.id));
+        });
+        return { resources: items.slice(0, MAX_RESOURCES), unavailable };
+    }
+    /**
+     * 解析消息附件：以发送者的凭据**并行**读取每个资源（打码、每个限 {@link MAX_ATTACHMENT_CHARS} 字符；总时限
+     * min(`tools.timeoutMs`, 30s)），按请求顺序返回要追加在用户消息后的文本块与元数据。名称取资源清单里的 name
+     * （读不到清单时用 URI）。连接器的 `read_resource` 工具被管理员停用 → 409 `connector.resources_disabled`。
+     * 任一附件失败整条消息失败（不写入）。
+     */
+    async resolveAttachments(orgId, accountId, refs) {
+        const apps = new Map();
+        for (const id of new Set(refs.map((r) => r.connectorId)))
+            apps.set(id, await this.connectorRow(orgId, id));
+        const enabled = await this.resourcesEnabled([...apps.keys()]);
+        for (const id of apps.keys()) {
+            if (!enabled.has(id)) {
+                throw new ApiError("connector.resources_disabled", "Reading resources is turned off for this connector");
+            }
+        }
+        const timeoutMs = Math.min(this.d.config().tools.timeoutMs, ATTACHMENTS_TIMEOUT_MS);
+        const read = await Promise.all(refs.map(async (ref) => {
+            const app = apps.get(ref.connectorId);
+            const got = await this.withSession(orgId, app, accountId, timeoutMs, async (s) => {
+                if (!s.readResource)
+                    return undefined;
+                const listed = s.listResources
+                    ? (await s.listResources().catch(() => [])).find((r) => r.uri === ref.uri)
+                    : undefined;
+                const result = await s.readResource(ref.uri);
+                return { name: listed?.name ?? ref.uri, text: renderResult(result).text };
+            });
+            if (!got)
+                throw new ApiError("connector.not_found", "This connector does not provide resources");
+            return { app, ref, got };
+        }));
+        const blocks = [];
+        const attachments = [];
+        for (const { app, ref, got } of read) {
+            let body = got.text;
+            if (body.length > MAX_ATTACHMENT_CHARS) {
+                body = `${body.slice(0, MAX_ATTACHMENT_CHARS)}\n[Attachment truncated: showing the first ${MAX_ATTACHMENT_CHARS} of ${got.text.length} characters.]`;
+            }
+            blocks.push({
+                type: "text",
+                text: `Attached resource ${JSON.stringify(got.name)} (${ref.uri}) from app ${app.name}:\n\n${body}`,
+            });
+            attachments.push({ appId: app.id, appName: app.name, uri: ref.uri, name: got.name });
+        }
+        return { blocks, attachments };
+    }
+}

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

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { ConnectorDetail, ConnectorPreview, ConnectorSummary, ConnectorsService, 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>;
+    connector: z.ZodString;
+    endpoint: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    auth: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"bearer">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+        in: z.ZodEnum<{
+            header: "header";
+            query: "query";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"basic">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"headers">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+        names: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth_code">;
+        ownership: z.ZodLiteral<"personal">;
+        discovery: z.ZodEnum<{
+            manual: "manual";
+            mcp: "mcp";
+        }>;
+        authorizationUrl: z.ZodOptional<z.ZodURL>;
+        tokenUrl: z.ZodOptional<z.ZodURL>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        client: z.ZodEnum<{
+            dcr: "dcr";
+            manual: "manual";
+        }>;
+        tokenAuthMethod: z.ZodOptional<z.ZodEnum<{
+            client_secret_basic: "client_secret_basic";
+            client_secret_post: "client_secret_post";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth_client">;
+        ownership: z.ZodLiteral<"org">;
+        tokenUrl: z.ZodURL;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tokenAuthMethod: z.ZodOptional<z.ZodEnum<{
+            client_secret_basic: "client_secret_basic";
+            client_secret_post: "client_secret_post";
+        }>>;
+    }, z.core.$strict>], "type">;
+    credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/** 预览（Ruling A20）：与创建相同的连接器 / 端点 / 认证 / 凭据，认证可缺省（只读端点描述，不列工具）。 */
+declare const PreviewBody: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    connector: z.ZodString;
+    endpoint: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    auth: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"bearer">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+        in: z.ZodEnum<{
+            header: "header";
+            query: "query";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"basic">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"headers">;
+        ownership: z.ZodEnum<{
+            org: "org";
+            personal: "personal";
+        }>;
+        names: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth_code">;
+        ownership: z.ZodLiteral<"personal">;
+        discovery: z.ZodEnum<{
+            manual: "manual";
+            mcp: "mcp";
+        }>;
+        authorizationUrl: z.ZodOptional<z.ZodURL>;
+        tokenUrl: z.ZodOptional<z.ZodURL>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        client: z.ZodEnum<{
+            dcr: "dcr";
+            manual: "manual";
+        }>;
+        tokenAuthMethod: z.ZodOptional<z.ZodEnum<{
+            client_secret_basic: "client_secret_basic";
+            client_secret_post: "client_secret_post";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth_client">;
+        ownership: z.ZodLiteral<"org">;
+        tokenUrl: z.ZodURL;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tokenAuthMethod: z.ZodOptional<z.ZodEnum<{
+            client_secret_basic: "client_secret_basic";
+            client_secret_post: "client_secret_post";
+        }>>;
+    }, z.core.$strict>], "type">>;
+    credential: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+declare const ReviewBody: z.ZodObject<{
+    action: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+    }>;
+}, z.core.$strict>;
+declare const UpdateBody: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<{
+            disabled: "disabled";
+            enabled: "enabled";
+        }>>;
+        defaultPolicy: z.ZodOptional<z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+            deny: "deny";
+        }>>;
+    }, z.core.$strict>>>;
+    allowUnannotated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
+ * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
+ */
+export declare class ConnectorsController {
+    private readonly connectors;
+    constructor(connectors: ConnectorsService);
+    list(org: OrgContext): Promise<{
+        connectors: ConnectorSummary[];
+    }>;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
+        connector: ConnectorDetail;
+        issues: ToolIssue[];
+    }>;
+    /**
+     * 预览（安装向导）：读端点描述（认证提示、操作清单）并在能认证时列出工具，什么都不写。
+     * 创建与预览的请求体可带最大 2 MB 的 OpenAPI 文档，路由级 bodyLimit 见 http/app.ts。
+     */
+    preview(principal: Principal, org: OrgContext, body: z.infer<typeof PreviewBody>): Promise<ConnectorPreview>;
+    get(principal: Principal, org: OrgContext, connectorId: string): Promise<{
+        connector: ConnectorDetail;
+    }>;
+    update(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof UpdateBody>): Promise<{
+        connector: ConnectorDetail;
+    }>;
+    remove(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
+    refresh(principal: Principal, org: OrgContext, connectorId: string): Promise<{
+        connector: ConnectorDetail;
+        issues: ToolIssue[];
+        changes: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
+    }>;
+    /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
+    review(principal: Principal, org: OrgContext, connectorId: string, name: string, body: z.infer<typeof ReviewBody>): Promise<{
+        connector: ConnectorDetail;
+    }>;
+    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>;
+    clearMyCredential(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
+}
+export {};