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

package/dist/connector.d.ts

@@ -0,0 +1,154 @@
+import type { ZodTypeAny } from "zod";
+import type { FormAnswer, ToolContent, ToolResult, ToolSpec } from "./tool.js";
+/** 注入到出站请求的鉴权信息。 */
+export interface AuthInjection {
+    headers: Record<string, string>;
+    query?: Record<string, string>;
+}
+/** 连接器与远端服务的一次会话。 */
+export interface ConnectorSession {
+    listTools(): Promise<ToolSpec[]>;
+    /**
+     * `ctx.spec`：内核快照里该工具已复核的定义（`connector_tools.spec`，绝不是待复核的新定义），含 listTools 时给出的
+     * `connectorData`。连接器应按它路由调用，而不是重新读取远端描述（远端变化须先经漂移复核）。旧内核不传，须判空。
+     */
+    callTool(name: string, input: unknown, signal: AbortSignal, ctx?: {
+        spec: ToolSpec;
+    }): Promise<ToolResult>;
+    listResources?(): Promise<{
+        uri: string;
+        name: string;
+        description?: string;
+        mimeType?: string;
+    }[]>;
+    readResource?(uri: string): Promise<ToolResult>;
+    /** 可选：远端提供的提示模板（如 MCP prompts）。不支持时不实现，内核须判空。 */
+    listPrompts?(): Promise<PromptInfo[]>;
+    /** 可选：按参数渲染一个提示模板，返回消息（如 MCP `prompts/get`）。失败抛 ToolError（英文、不含凭据）。 */
+    getPrompt?(name: string, args: Record<string, string>): Promise<RenderedPrompt>;
+    close(): Promise<void>;
+}
+/** 远端提示模板（`/连接器:提示名` 斜杠命令）。 */
+export interface PromptInfo {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+}
+/** 渲染后的提示：按顺序的消息，内容块同工具结果（非文本给类型说明）。 */
+export interface RenderedPrompt {
+    description?: string;
+    messages: {
+        role: "user" | "assistant";
+        content: ToolContent[];
+    }[];
+}
+/**
+ * 远端在一次调用中途向用户要输入（MCP `elicitation/create`）：
+ * - `form`：`requestedSchema` 是远端给的扁平 JSON Schema（object + 原始类型属性），由内核映射成交互表单；
+ * - `url`：请用户在浏览器里打开 `url` 完成某步（授权、付款、填敏感信息），完成与否由用户确认。
+ */
+export type ElicitationRequest = {
+    mode: "form";
+    message: string;
+    requestedSchema: Record<string, unknown>;
+} | {
+    mode: "url";
+    message: string;
+    url: string;
+    elicitationId: string;
+};
+/** 对 elicitation 的答复（与 MCP `ElicitResult` 对应）：接受（带表单内容）/ 拒绝 / 取消。 */
+export type ElicitationResponse = {
+    action: "accept";
+    content?: FormAnswer;
+} | {
+    action: "decline";
+} | {
+    action: "cancel";
+};
+/** 内核打开会话时传给连接器的参数。 */
+export interface ConnectorOpenArgs {
+    /** 已按 endpointSchema 校验。 */
+    endpoint: unknown;
+    /** 每次请求前调用，凭据的刷新由内核负责。 */
+    auth: () => Promise<AuthInjection>;
+    /** 收到 401 时调用一次；内核刷新凭据后，插件重试一次。 */
+    onUnauthorized: () => Promise<void>;
+    signal: AbortSignal;
+    /**
+     * 会话期间远端报告工具清单变了（如 MCP `notifications/tools/list_changed`）时调用，可能多次；内核据此安排一次
+     * 漂移检查（新的 / 变了的工具在管理员复核前不可用）。可选：旧内核不提供，连接器须判空。不要等待它、不要因它抛错。
+     */
+    onToolsChanged?: () => void;
+    /**
+     * Called when the remote asks the user for input mid-call (MCP `elicitation/create`, the URL-mode
+     * `-32042` error); the connector passes the returned answer back to the remote as is. Optional:
+     * when the kernel does not provide it, the connector does not declare the MCP elicitation
+     * capability (so the remote never starts one).
+     *
+     * 内核不能在等用户回答期间保持远端调用（运行会暂停、worker 释放、会话关闭）：需要问用户时，内核**中止本次调用**
+     * （经 `callTool` 的 signal）并让运行进入等待；用户回答后内核重新发起同一调用，远端再次发起同样的 elicitation 时
+     * 由本回调立即用用户的答案答复。所以连接器只需「收到就调用、拿到就回」，不要自己缓存或重试；需要问用户时本回调
+     * 以错误拒绝（调用已被中止），连接器让该错误原样结束本次调用即可。
+     */
+    onElicit?: (request: ElicitationRequest) => Promise<ElicitationResponse>;
+}
+/**
+ * 远端描述里声明的一种认证方式，映射到内核连接器认证（ConnectorAuth）的形状，供安装向导预填。
+ * `scheme` 是远端描述里的名字（如 OpenAPI `securitySchemes` 的键），`description` 原样给出（可能缺省）。
+ * 只列内核支持的方式；其余（cookie 里的 API key、OpenID Connect、implicit / password 流等）不出现。
+ */
+export type AuthHint = {
+    scheme: string;
+    description?: string;
+} & ({
+    type: "bearer";
+} | {
+    type: "basic";
+} | {
+    type: "api_key";
+    in: "header" | "query";
+    name: string;
+} | {
+    type: "oauth_client";
+    tokenUrl: string;
+    scopes: string[];
+} | {
+    type: "oauth_code";
+    authorizationUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+});
+/** 远端描述里的一个操作（如 OpenAPI operation），供安装向导勾选。 */
+export interface ConnectorOperation {
+    /** 端点配置里勾选用的 id（如 OpenAPI 的 operationId）。 */
+    id: string;
+    /** 大写 HTTP 方法。 */
+    method: string;
+    path: string;
+    summary?: string;
+}
+/** `Connector.inspect` 的结果。 */
+export interface ConnectorInspection {
+    authHints: AuthHint[];
+    operations?: ConnectorOperation[];
+}
+/** `connector@1`：插件实现、内核调用。 */
+export interface Connector {
+    kind: string;
+    endpointSchema: ZodTypeAny;
+    open(args: ConnectorOpenArgs): Promise<ConnectorSession>;
+    /**
+     * 可选：不带凭据读取端点的描述（安装向导的预览用），返回声明的认证方式与可选的操作清单。
+     * `endpoint` 已按 endpointSchema 校验。失败抛 ToolError（消息英文、不含凭据）。旧连接器不实现，内核须判空。
+     */
+    inspect?(args: {
+        endpoint: unknown;
+        signal: AbortSignal;
+    }): Promise<ConnectorInspection>;
+}

package/dist/connector.js

@@ -0,0 +1 @@
+export {};

package/dist/ctx.d.ts

@@ -0,0 +1,176 @@
+import type { Kysely } from "kysely";
+import type { ExtensionPointRef } from "./extension-point.js";
+import type { AvailableHook, HookHandler, HookOptions } from "./hooks.js";
+import type { ObjectHead, PresignedUpload, PresignGetOptions } from "./storage.js";
+import type { ToolHandler, ToolSpec } from "./tool.js";
+import type { EmbedClaims, UiActionArgs, UiActionResult, UiRenderArgs, UiView } from "./ui.js";
+/** 日志接口。 */
+export interface Logger {
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+}
+/** 分布式锁租约。 */
+export interface Lease {
+    renew(): Promise<boolean>;
+    release(): Promise<void>;
+}
+/**
+ * 插件的对象存储（`ctx.storage`，需 `permissions.storage`）：与 `ObjectStore` 同形，但每个方法的第一个参数是
+ * `orgId`，键与前缀由内核自动加上 `plugins/<插件名>/<orgId>/`——插件只能看到自己在该组织下的对象。
+ * 底层是部署配置的 `object-store@1` 提供方；没有提供方时各方法抛错。
+ */
+export interface ExtensionStorage {
+    put(orgId: string, key: string, body: Uint8Array | ReadableStream<Uint8Array>, opts: {
+        contentType: string;
+        size?: number;
+        signal?: AbortSignal;
+    }): Promise<ObjectHead>;
+    /**
+     * 不存在返回 null。`range` 为闭区间字节范围，缺省 `end` 表示读到末尾。
+     * 带 `range` 时 `head.size` 仍是整个对象的大小；存储忽略 Range 时 body 可能是整个对象。
+     */
+    get(orgId: string, key: string, opts?: {
+        signal?: AbortSignal;
+        range?: {
+            start: number;
+            end?: number;
+        };
+    }): Promise<{
+        head: ObjectHead;
+        body: ReadableStream<Uint8Array>;
+    } | null>;
+    head(orgId: string, key: string): Promise<ObjectHead | null>;
+    /** 不存在也算成功。 */
+    delete(orgId: string, key: string): Promise<void>;
+    deletePrefix(orgId: string, prefix: string): Promise<number>;
+    list(orgId: string, prefix: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: ObjectHead[];
+        cursor?: string;
+    }>;
+    presignGet(orgId: string, key: string, opts: PresignGetOptions): Promise<string>;
+    presignPut(orgId: string, key: string, opts: {
+        contentType: string;
+        maxSize: number;
+        ttlSeconds: number;
+    }): Promise<PresignedUpload>;
+}
+/** 传给插件 `setup` 的上下文。不提供定时器与进程内共享状态；kv 写入必须带 TTL。 */
+export interface ExtensionContext {
+    kv: {
+        get(key: string): Promise<string | null>;
+        set(key: string, value: string, opts: {
+            ttlSeconds: number;
+        }): Promise<void>;
+        del(key: string): Promise<void>;
+        incr(key: string, opts: {
+            ttlSeconds: number;
+        }): Promise<number>;
+    };
+    lock: {
+        acquire(key: string, opts: {
+            ttlMs: number;
+        }): Promise<Lease | null>;
+    };
+    bus: {
+        publish(topic: string, payload: unknown): Promise<void>;
+        subscribe(topic: string, handler: (payload: unknown) => void): Promise<() => Promise<void>>;
+    };
+    queue: {
+        define<T>(name: string, handler: (data: T) => Promise<void>, opts?: {
+            concurrency?: number;
+        }): void;
+        add<T>(name: string, data: T, opts?: {
+            delayMs?: number;
+            jobId?: string;
+        }): Promise<void>;
+    };
+    secrets: {
+        get(orgId: string, key: string): Promise<string | null>;
+        set(orgId: string, key: string, value: string): Promise<void>;
+    };
+    /** 对象存储（需 `permissions.storage`，见 {@link ExtensionStorage}）。 */
+    storage: ExtensionStorage;
+    /** 已切到本插件 schema（withSchema）的 Kysely 实例。 */
+    db: Kysely<any>;
+    http: {
+        /** 实际挂载到 `/plugins/<name><path>`。 */
+        route(method: "GET" | "POST" | "PUT" | "DELETE", path: string, handler: (req: Request) => Promise<Response>): void;
+    };
+    tools: {
+        /** 注册一个工具；只能在 `setup` 期间调用，名称不可重复。 */
+        register(spec: ToolSpec, handler: ToolHandler): void;
+    };
+    /**
+     * Consume extension points provided by other extensions: only non-brokered refs declared in the
+     * manifest's `requires` / `optional`. Without `orgId` it is the deployment-level view and returns
+     * synchronously; with `orgId` it returns a Promise, and orgScoped extension points (such as
+     * `channel`, `directory`) are filtered by that org's enablement (queried every time, not cached);
+     * `get` rejects with `ExtensionPointUnavailableError` when the provider is not enabled in that org.
+     * When there is no provider, `get` throws `ExtensionPointUnavailableError` and `list` returns an
+     * empty list.
+     */
+    extensionPoints: {
+        /** `provider` may be omitted for a single-select extension point; required for multi-select. */
+        get<T>(ref: ExtensionPointRef, provider?: string): T;
+        get<T>(ref: ExtensionPointRef, provider: string | undefined, opts: {
+            orgId: string;
+        }): Promise<T>;
+        list<T>(ref: ExtensionPointRef): {
+            plugin: string;
+            impl: T;
+        }[];
+        list<T>(ref: ExtensionPointRef, opts: {
+            orgId: string;
+        }): Promise<{
+            plugin: string;
+            impl: T;
+        }[]>;
+    };
+    /**
+     * 界面贡献的运行时（清单 `ui` + `permissions.ui`）：
+     * - `view` / `action`：只能在 `setup` 期间注册，id 是清单里 kind view 的贡献 id；
+     *   `action` 收到视图里按钮或表单提交（`args.actionId` 区分是哪一个）；
+     * - `invalidate`：告诉内核「这个贡献变了」，打开着它的网页会重新取视图（经 bus，跨副本）；
+     * - `verifyEmbedToken`：校验 embed 页面拿到的嵌入令牌，只认签给本插件、未过期的，且此刻插件仍在该组织启用、
+     *   调用者仍是 active 成员（组织页面还要求 member 以上），否则返回 null；返回的 `role` 是此刻的角色。
+     */
+    ui: {
+        view(id: string, render: (args: UiRenderArgs) => Promise<UiView>): void;
+        action(id: string, handler: (args: UiActionArgs) => Promise<UiActionResult>): void;
+        invalidate(target: {
+            orgId: string;
+            conversationId?: string;
+            contribution: string;
+        }): Promise<void>;
+        verifyEmbedToken(token: string): Promise<EmbedClaims | null>;
+    };
+    /**
+     * Hooks (`permissions.hooks`): observe model and tool calls, or deny them with a policy hook.
+     * `on` is only allowed during `setup`; the mount point must be declared in `permissions.hooks` and be
+     * one of `HOOKS_AVAILABLE`; `mode: "policy"` only on `POLICY_HOOKS` and only for mount points also
+     * declared in `permissions.policyHooks`. Hooks fire only for organizations
+     * that enabled the plugin, only in chat conversations (never in eval replays); see `HookOptions` for
+     * how policy and observe hooks run. Unloading, upgrading or disabling the plugin instance revokes
+     * them (in-flight hook calls are drained like tool calls).
+     */
+    hooks: {
+        on<K extends AvailableHook>(mount: K, handler: HookHandler<K>, opts: HookOptions): void;
+    };
+    provide(extensionPoint: ExtensionPointRef, impl: unknown): void;
+    /**
+     * 本插件实例的生命周期信号：实例被撤销（停用、卸载、升级）时、在途调用排空之后中止。
+     * 插件自己起的长任务（轮询循环、长连接等）据此收尾。
+     */
+    signal: AbortSignal;
+    /**
+     * 部署级配置，已按插件 schema 校验（启动配置与企业管理员在后台保存的值合并后）。这是一个 getter：
+     * 标了 `hot`（`.meta({ hot: true })`）的字段改动时内核就地替换，插件**在用时读** `ctx.config` 才能拿到新值，
+     * 不要在 setup 里把 hot 字段拷进闭包；改了非 hot 字段时内核重新加载插件实例（新的 setup）。
+     */
+    readonly config: unknown;
+    log: Logger;
+}

package/dist/ctx.js

@@ -0,0 +1 @@
+export {};

package/dist/define-extension.d.ts

@@ -0,0 +1,41 @@
+import type { z } from "zod";
+import type { ExtensionContext } from "./ctx.js";
+import { type ExtensionPointRef } from "./extension-point.js";
+import { type ExtensionPermissions } from "./permissions.js";
+import type { UiContribution } from "./ui.js";
+/** 插件清单。 */
+export interface ExtensionManifest {
+    name: string;
+    version: string;
+    sdk: string;
+    provides: ExtensionPointRef[];
+    requires?: ExtensionPointRef[];
+    /** 可选依赖：缺失时插件照常加载，运行时经 ctx.extensionPoints 判断。 */
+    optional?: ExtensionPointRef[];
+    /** 权限清单（治理而非沙箱）。 */
+    permissions?: ExtensionPermissions;
+    /** 界面贡献：对话页标签与组织页面；id 须同时列在 `permissions.ui` 里。 */
+    ui?: UiContribution[];
+    config?: {
+        deployment?: z.ZodTypeAny;
+        org?: z.ZodTypeAny;
+    };
+    migrations?: string;
+    setup(ctx: ExtensionContext): void | Promise<void>;
+    /**
+     * 可选：插件实例被撤销（停用、卸载、升级换新实例、依赖方随提供方重新加载）时调用。
+     * 调用时内核已经：停止接新的调用、等在途调用结束（最多 `extensionHost.drainSeconds`）、中止 `ctx.signal`、
+     * 撤销本实例经 ctx 做过的全部登记（工具、路由、队列 worker、bus 订阅、锁租约、界面、provide）。
+     * 这里只收拾插件自己在 ctx 之外开的东西（如自建的连接）；不要再经 ctx 登记任何东西。
+     * setup 抛错时不调用（已登记的由内核撤销）。
+     */
+    dispose?(ctx: ExtensionContext): void | Promise<void>;
+}
+/** 插件清单不合法。 */
+export declare class ExtensionManifestError extends Error {
+    constructor(plugin: string, message: string);
+}
+/** 插件名规则（清单 `name`；连接器模板的 `plugin` 也按它校验）。 */
+export declare const EXTENSION_NAME_RE: RegExp;
+/** 校验并原样返回插件清单；不合法抛 ExtensionManifestError。 */
+export declare function defineExtension(m: ExtensionManifest): ExtensionManifest;

package/dist/define-extension.js

@@ -0,0 +1,85 @@
+import semver from "semver";
+import { EXTENSION_POINTS, parseExtensionPoint, } from "./extension-point.js";
+import { validatePermissions, validateUiContributions, } from "./permissions.js";
+/** 插件清单不合法。 */
+export class ExtensionManifestError extends Error {
+    constructor(plugin, message) {
+        super(`extension ${plugin}: ${message}`);
+        this.name = "ExtensionManifestError";
+    }
+}
+/** 插件名规则（清单 `name`；连接器模板的 `plugin` 也按它校验）。 */
+export const EXTENSION_NAME_RE = /^[a-z][a-z0-9-]{1,40}$/;
+const NAME_RE = EXTENSION_NAME_RE;
+/** 保留的插件名：内核用 `kernel` 作为自己的 secrets 命名空间，插件不能与之相同。 */
+const RESERVED_NAMES = new Set(["kernel"]);
+function checkRefs(label, refs, fail, forbidBrokered = false) {
+    for (const ref of refs) {
+        let name;
+        try {
+            name = parseExtensionPoint(ref).name;
+        }
+        catch {
+            fail(`${label} entry "${ref}" is not a valid extension point ref`);
+        }
+        if (!Object.hasOwn(EXTENSION_POINTS, name)) {
+            fail(`${label} entry "${ref}" references unregistered extension point "${name}"`);
+        }
+        if (forbidBrokered && EXTENSION_POINTS[name]?.brokered) {
+            fail(`${label} entry "${ref}" is a brokered extension point and is used through the platform`);
+        }
+    }
+}
+/** 校验并原样返回插件清单；不合法抛 ExtensionManifestError。 */
+export function defineExtension(m) {
+    const plugin = typeof m?.name === "string" && m.name !== "" ? m.name : "<unnamed>";
+    const fail = (msg) => {
+        throw new ExtensionManifestError(plugin, msg);
+    };
+    if (typeof m.name !== "string" || !NAME_RE.test(m.name)) {
+        fail(`field "name" must match ${NAME_RE}`);
+    }
+    if (RESERVED_NAMES.has(m.name))
+        fail(`field "name" "${m.name}" is reserved`);
+    if (typeof m.version !== "string" || semver.valid(m.version) === null) {
+        fail(`field "version" must be a valid semver version`);
+    }
+    if (typeof m.sdk !== "string" || semver.validRange(m.sdk) === null) {
+        fail(`field "sdk" must be a valid semver range`);
+    }
+    if (typeof m.setup !== "function")
+        fail(`field "setup" must be a function`);
+    if (m.dispose !== undefined && typeof m.dispose !== "function") {
+        fail(`field "dispose" must be a function when present`);
+    }
+    if (!Array.isArray(m.provides))
+        fail(`field "provides" must be an array`);
+    checkRefs("provides", m.provides, fail);
+    if (new Set(m.provides).size !== m.provides.length) {
+        fail(`field "provides" has duplicate entries`);
+    }
+    const requires = m.requires ?? [];
+    checkRefs("requires", requires, fail, true);
+    for (const r of requires) {
+        if (m.provides.includes(r))
+            fail(`field "requires" entry "${r}" is also provided by the same plugin`);
+    }
+    const optional = m.optional ?? [];
+    if (!Array.isArray(optional))
+        fail(`field "optional" must be an array`);
+    checkRefs("optional", optional, fail, true);
+    for (const r of optional) {
+        if (m.provides.includes(r) || requires.includes(r)) {
+            fail(`field "optional" entry "${r}" overlaps with "provides" or "requires"`);
+        }
+    }
+    if (m.permissions !== undefined) {
+        const errs = validatePermissions(plugin, m.permissions);
+        if (errs.length > 0)
+            fail(`invalid permissions: ${errs.join("; ")}`);
+    }
+    const uiErrs = validateUiContributions(m.ui, m.permissions);
+    if (uiErrs.length > 0)
+        fail(`invalid ui: ${uiErrs.join("; ")}`);
+    return m;
+}

package/dist/directory.d.ts

@@ -0,0 +1,29 @@
+export interface DirectoryMember {
+    externalId: string;
+    tenantId: string;
+    email?: string;
+    emailVerified: boolean;
+    displayName: string;
+    active: boolean;
+}
+export interface Directory {
+    /**
+     * Optional: whether this org-level config has the directory fully set up (e.g. every required
+     * credential filled in). Implement it in an extension whose directory fields are optional in the
+     * org-level config (the same extension also provides other extension points such as a channel, and
+     * an org that uses only those leaves the directory config empty). When it returns false the kernel
+     * treats the directory as "not configured": the hourly scan, `directory_changed` and the
+     * pre-removal recheck are skipped silently (no job, no audit, no warning), and a manual sync by an
+     * admin returns 409 `directory.not_configured`. When not implemented, any config that satisfies
+     * the schema counts as configured. Must be a pure function (no requests, never throws).
+     */
+    configured?(orgConfig: unknown): boolean;
+    listMembers(args: {
+        orgConfig: unknown;
+        cursor?: string;
+        signal: AbortSignal;
+    }): Promise<{
+        members: DirectoryMember[];
+        next?: string;
+    }>;
+}

package/dist/directory.js

@@ -0,0 +1 @@
+export {};

package/dist/extension-point.d.ts

@@ -0,0 +1,29 @@
+/** Extension point ref, of the form `channel@1` (name@major). */
+export type ExtensionPointRef = `${string}@${number}`;
+/** Extension point cardinality: `single` allows one provider at a time, `multi` allows several. */
+export type Cardinality = "single" | "multi";
+/** Registry entry of an extension point. */
+export interface ExtensionPointInfo {
+    cardinality: Cardinality;
+    /** Brokered by the platform API (extensions may not `requires` it; they use it only through `ctx`). */
+    brokered: boolean;
+    /** Enabled per org (consumers may pass `orgId` to check that the org enabled the provider). */
+    orgScoped: boolean;
+}
+/** The registered extension points. */
+export declare const EXTENSION_POINTS: Record<string, ExtensionPointInfo>;
+/** Cardinality of the registered extension points (derived from EXTENSION_POINTS). */
+export declare const EXTENSION_POINT_CARDINALITY: Record<string, Cardinality>;
+/** Connector extension point ref (see `connector.ts`). */
+export declare const CONNECTOR_EXTENSION_POINT = "connector@1";
+/** IM channel extension point ref (see `channel.ts`). */
+export declare const CHANNEL_EXTENSION_POINT = "channel@1";
+/** Third-party login identity source extension point ref (see `identity.ts`). */
+export declare const IDENTITY_SOURCE_EXTENSION_POINT = "identity-source@1";
+/** Directory sync extension point ref (see `directory.ts`). */
+export declare const DIRECTORY_EXTENSION_POINT = "directory@1";
+/** Parses an extension point ref; throws when the format is invalid. */
+export declare function parseExtensionPoint(ref: string): {
+    name: string;
+    major: number;
+};

package/dist/extension-point.js

@@ -0,0 +1,36 @@
+const info = (cardinality, brokered = false, orgScoped = false) => ({
+    cardinality,
+    brokered,
+    orgScoped,
+});
+/** The registered extension points. */
+export const EXTENSION_POINTS = {
+    sandbox: info("single", true),
+    "config-source": info("single"),
+    "secret-store": info("single", true),
+    "object-store": info("single", true),
+    channel: info("multi", false, true),
+    "model-provider": info("multi", true),
+    "identity-source": info("multi"),
+    directory: info("multi", false, true),
+    counter: info("multi"),
+    connector: info("multi", true),
+    "file-preview": info("multi", false, true),
+};
+/** Cardinality of the registered extension points (derived from EXTENSION_POINTS). */
+export const EXTENSION_POINT_CARDINALITY = Object.fromEntries(Object.entries(EXTENSION_POINTS).map(([k, v]) => [k, v.cardinality]));
+/** Connector extension point ref (see `connector.ts`). */
+export const CONNECTOR_EXTENSION_POINT = "connector@1";
+/** IM channel extension point ref (see `channel.ts`). */
+export const CHANNEL_EXTENSION_POINT = "channel@1";
+/** Third-party login identity source extension point ref (see `identity.ts`). */
+export const IDENTITY_SOURCE_EXTENSION_POINT = "identity-source@1";
+/** Directory sync extension point ref (see `directory.ts`). */
+export const DIRECTORY_EXTENSION_POINT = "directory@1";
+/** Parses an extension point ref; throws when the format is invalid. */
+export function parseExtensionPoint(ref) {
+    const m = /^([a-z][a-z0-9-]*)@(\d+)$/.exec(ref);
+    if (!m)
+        throw new Error(`invalid extension point ref "${ref}", expected "<name>@<major>"`);
+    return { name: m[1], major: Number(m[2]) };
+}

package/dist/file-preview.d.ts

@@ -0,0 +1,64 @@
+import type { Locale } from "./cards.js";
+import type { UiView } from "./ui.js";
+/** File previewer extension point ref (UI refresh spec §5.8). */
+export declare const FILE_PREVIEW_EXTENSION_POINT = "file-preview@1";
+/** Largest file a previewer may declare (`FilePreviewer.maxBytes`): 20 MiB. */
+export declare const FILE_PREVIEW_MAX_BYTES: number;
+/**
+ * One previewer of a `file-preview@1` provider: which files it previews and how. It renders either a
+ * view (`render`, drawn by the web app like any `UiView`) or an embed page (`embed`, the id of a ui
+ * contribution `{ kind: "embed", place: "file-preview" }` of the same extension, which receives the
+ * file over the message bridge). Exactly one of the two.
+ */
+export interface FilePreviewer {
+    /** Unique within the extension, `[a-z0-9-]{1,40}`. */
+    id: string;
+    title: {
+        zh: string;
+        en: string;
+    };
+    /**
+     * Files it accepts: MIME types (`image/*` wildcards allowed) and / or file extensions (with or
+     * without the dot; matched case-insensitively). At least one entry.
+     */
+    accepts: {
+        mimeTypes?: string[];
+        extensions?: string[];
+    };
+    /** Largest file it previews, at most {@link FILE_PREVIEW_MAX_BYTES}. */
+    maxBytes: number;
+    render?(args: FilePreviewArgs): Promise<UiView>;
+    embed?: string;
+}
+/** What a `file-preview@1` extension provides (`ctx.provide("file-preview@1", provider)`). */
+export interface FilePreviewProvider {
+    previewers: FilePreviewer[];
+}
+/** Arguments of {@link FilePreviewer.render}; identities come from the kernel after authentication. */
+export interface FilePreviewArgs {
+    orgId: string;
+    accountId: string;
+    conversationId: string;
+    locale: Locale;
+    /** Aborted at the kernel's time limit: stop reading and rendering. */
+    signal: AbortSignal;
+    file: {
+        id: string;
+        name: string;
+        contentType: string;
+        size: number;
+    };
+    /**
+     * The read grant: this one file's bytes, valid only during this call (rejects afterwards), and
+     * rejects a file over the previewer's `maxBytes`. The extension never gets a storage key or URL.
+     */
+    read(): Promise<Uint8Array>;
+}
+/** Checks a `file-preview@1` provider; returns the problems (empty = valid). */
+export declare function validateFilePreviewProvider(p: unknown): string[];
+/** Whether a previewer takes this file: its type or extension is accepted and it is within `maxBytes`. */
+export declare function previewerAccepts(p: Pick<FilePreviewer, "accepts" | "maxBytes">, file: {
+    name: string;
+    contentType: string;
+    size: number;
+}): boolean;