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

package/dist/extensions/sources.d.ts

@@ -0,0 +1,69 @@
+import type { KernelDb } from "../db/kernel-schema.js";
+/**
+ * Where an extension comes from (C15 / C13):
+ * - `config`: the startup config's `extensions` list (development mode and existing deployments),
+ *   read-only in the admin console;
+ * - `install`: PG install records (`extension_installs`), the package in the content-addressed package
+ *   store, synced to local disk by each replica before loading. The bootstrap plugins (package
+ *   ecosystem spec §7, which replaced the builtin extensions) are install records too; where an
+ *   install came from is `extension_installs.source`.
+ * On a name clash config > install, and the skipped one warns.
+ */
+export type ExtensionSource = "config" | "install";
+/** 副本（进程）id：`<hostname>-<pid>-<6 位随机>`，每个进程唯一（`http.replicaId` 可能跨重启不变或多副本相同）。 */
+export declare function newReplicaId(): string;
+/** Why `extension_replica_status.state = pending` (F-I: the admin view derives pending_config and so on from it). */
+export type PendingReason = "config" | "approval" | "migration" | "dependency";
+/** One load result (written to `extension_replica_status`). */
+export interface ExtensionLoadStatus {
+    plugin: string;
+    version: string;
+    sha256: string | null;
+    source: ExtensionSource;
+    /** `unloaded`：本进程撤销了它（停用 / 卸载，或随提供方卸下时 reason 为 `dependency`）。停机时删掉本副本的行。 */
+    state: "loaded" | "failed" | "pending" | "unloaded";
+    reason: PendingReason | string | null;
+    detail: string | null;
+    /**
+     * 这一行的版本没加载成（failed / pending）而本副本仍在用旧版本（升级失败或待批准时旧版照常）时，旧版本号。
+     * 省略视同 null。
+     */
+    servingVersion?: string | null;
+}
+/** This replica's extension load status (PG `extension_replica_status`; each replica writes only its own rows). */
+export declare class ReplicaStatusStore {
+    private readonly db;
+    readonly replicaId: string;
+    private readonly httpReplicaId?;
+    private readonly redact;
+    /** 本进程写过行（停机时才需要删；没写过时不碰数据库，例如启动在迁移前就失败）。 */
+    private wrote;
+    /**
+     * @param redact 写 `detail` 之前打码（内核传 logger 的 `redact`：报错信息里可能带着插件拼进去的密钥）。
+     */
+    constructor(db: KernelDb, replicaId: string, httpReplicaId?: string | undefined, redact?: (text: string) => string);
+    /** 打码后截断到 {@link MAX_DETAIL}。 */
+    private cleanDetail;
+    /** 写入（覆盖）本副本该插件的一行，心跳取当前时间。 */
+    write(s: ExtensionLoadStatus): Promise<void>;
+    /**
+     * 给本副本该插件已有的一行补一句说明（不改状态），如「同名安装记录被忽略」。
+     * 该插件这一行属于生效的那一方（配置声明），所以只追加 detail。
+     */
+    note(plugin: string, detail: string): Promise<void>;
+    /**
+     * 心跳：本副本全部行的 `heartbeat_at` 取当前时间（每次 reconcile 之后调用；读状态的一方只算心跳不超过
+     * 3 个 reconcile 周期的副本，C16）。
+     */
+    heartbeat(): Promise<void>;
+    /**
+     * 清理：删掉本副本已不认识的插件的行（卸载后的名字，`keep` 为部署此刻已知的插件名），以及任何副本心跳超过
+     * `staleSeconds` 的行（副本已退出或崩溃；读的一方本来就不计入它们）。返回删除的行数。
+     */
+    prune(keep: readonly string[], staleSeconds: number): Promise<number>;
+    /**
+     * 正常停机：删掉本副本的全部行（尽力而为）。副本已不在，不该再计入部署状态（否则停机后约 3 个 reconcile
+     * 周期里一直显示「收敛中」）；崩溃的副本由 {@link prune} 按心跳清理。
+     */
+    removeAll(): Promise<void>;
+}

package/dist/extensions/sources.js

@@ -0,0 +1,120 @@
+import { randomBytes } from "node:crypto";
+import { hostname } from "node:os";
+import { sql } from "kysely";
+/** 副本（进程）id：`<hostname>-<pid>-<6 位随机>`，每个进程唯一（`http.replicaId` 可能跨重启不变或多副本相同）。 */
+export function newReplicaId() {
+    return `${hostname()}-${process.pid}-${randomBytes(3).toString("hex")}`;
+}
+/** detail 的长度上限（报错信息可能很长）。 */
+const MAX_DETAIL = 2000;
+/** This replica's extension load status (PG `extension_replica_status`; each replica writes only its own rows). */
+export class ReplicaStatusStore {
+    db;
+    replicaId;
+    httpReplicaId;
+    redact;
+    /** 本进程写过行（停机时才需要删；没写过时不碰数据库，例如启动在迁移前就失败）。 */
+    wrote = false;
+    /**
+     * @param redact 写 `detail` 之前打码（内核传 logger 的 `redact`：报错信息里可能带着插件拼进去的密钥）。
+     */
+    constructor(db, replicaId, httpReplicaId, redact = (t) => t) {
+        this.db = db;
+        this.replicaId = replicaId;
+        this.httpReplicaId = httpReplicaId;
+        this.redact = redact;
+    }
+    /** 打码后截断到 {@link MAX_DETAIL}。 */
+    cleanDetail(detail) {
+        return this.redact(detail).slice(0, MAX_DETAIL);
+    }
+    /** 写入（覆盖）本副本该插件的一行，心跳取当前时间。 */
+    async write(s) {
+        this.wrote = true;
+        const values = {
+            replica_id: this.replicaId,
+            plugin: s.plugin,
+            version: s.version,
+            sha256: s.sha256,
+            source: s.source,
+            state: s.state,
+            reason: s.reason,
+            detail: s.detail === null ? null : this.cleanDetail(s.detail),
+            serving_version: s.servingVersion ?? null,
+            http_replica_id: this.httpReplicaId ?? null,
+            heartbeat_at: sql `now()`,
+        };
+        await this.db
+            .insertInto("extension_replica_status")
+            .values(values)
+            .onConflict((oc) => oc.columns(["replica_id", "plugin"]).doUpdateSet({
+            version: values.version,
+            sha256: values.sha256,
+            source: values.source,
+            state: values.state,
+            reason: values.reason,
+            detail: values.detail,
+            serving_version: values.serving_version,
+            http_replica_id: values.http_replica_id,
+            heartbeat_at: values.heartbeat_at,
+        }))
+            .execute();
+    }
+    /**
+     * 给本副本该插件已有的一行补一句说明（不改状态），如「同名安装记录被忽略」。
+     * 该插件这一行属于生效的那一方（配置声明），所以只追加 detail。
+     */
+    async note(plugin, detail) {
+        await this.db
+            .updateTable("extension_replica_status")
+            .set({ detail: this.cleanDetail(detail) })
+            .where("replica_id", "=", this.replicaId)
+            .where("plugin", "=", plugin)
+            .execute();
+    }
+    /**
+     * 心跳：本副本全部行的 `heartbeat_at` 取当前时间（每次 reconcile 之后调用；读状态的一方只算心跳不超过
+     * 3 个 reconcile 周期的副本，C16）。
+     */
+    async heartbeat() {
+        if (!this.wrote)
+            return;
+        await this.db
+            .updateTable("extension_replica_status")
+            .set({ heartbeat_at: sql `now()` })
+            .where("replica_id", "=", this.replicaId)
+            .execute();
+    }
+    /**
+     * 清理：删掉本副本已不认识的插件的行（卸载后的名字，`keep` 为部署此刻已知的插件名），以及任何副本心跳超过
+     * `staleSeconds` 的行（副本已退出或崩溃；读的一方本来就不计入它们）。返回删除的行数。
+     */
+    async prune(keep, staleSeconds) {
+        let n = 0;
+        if (this.wrote) {
+            let q = this.db
+                .deleteFrom("extension_replica_status")
+                .where("replica_id", "=", this.replicaId);
+            if (keep.length > 0)
+                q = q.where("plugin", "not in", [...keep]);
+            n += Number((await q.executeTakeFirst()).numDeletedRows);
+        }
+        const r = await this.db
+            .deleteFrom("extension_replica_status")
+            .where("heartbeat_at", "<", sql `now() - make_interval(secs => ${staleSeconds})`)
+            .executeTakeFirst();
+        return n + Number(r.numDeletedRows);
+    }
+    /**
+     * 正常停机：删掉本副本的全部行（尽力而为）。副本已不在，不该再计入部署状态（否则停机后约 3 个 reconcile
+     * 周期里一直显示「收敛中」）；崩溃的副本由 {@link prune} 按心跳清理。
+     */
+    async removeAll() {
+        if (!this.wrote)
+            return;
+        await this.db
+            .deleteFrom("extension_replica_status")
+            .where("replica_id", "=", this.replicaId)
+            .execute();
+    }
+}

package/dist/extensions/sync.d.ts

@@ -0,0 +1,40 @@
+import { type ExtensionPackageLimits } from "./package.js";
+/**
+ * 把内容寻址的插件包同步到本副本的本地目录（C13）：`<dir>/<name>/<sha256 前 16 位>/`。
+ *
+ * - 目录里有校验文件 {@link MARKER} 且其中每个文件的 sha256 都对得上 → 直接复用（同一 sha 重启不再下载）；
+ * - 否则取包（`blobs.get` 按记录的存放位置读取并校验 sha256），先解到同级的临时目录、写好宿主包链接与校验文件，
+ *   再改名换入；目标位置的残缺目录先原子地改名移开再删（不原地删除，见 {@link clearBrokenRoot}）。并发的同机进程
+ *   各自解到自己的临时目录，改名失败时以已就位且完整的为准。
+ * - `node_modules/` 下为 {@link HOST_PROVIDED_PACKAGES} 建指向宿主副本的符号链接：插件 import 的 SDK 与 zod
+ *   就是内核用的那一份（同一模块实例）。插件目录不在宿主 `node_modules` 的上游，别的包一概解析不到。
+ */
+/** 从包存储取到的字节与安装记录的 sha256 不符。 */
+export declare class PackageShaMismatchError extends Error {
+    constructor(name: string, sha: string);
+}
+/** 解包完成后写入包根的校验文件（`wx` 写入：包里自带同名文件时同步失败）。 */
+export declare const MARKER = ".capybara-package.json";
+export interface Marker {
+    sha256: string;
+    entry: string;
+    /** 包内文件（相对包根） → sha256。 */
+    files: Record<string, string>;
+}
+/**
+ * 同步一个包到本地并返回 entry 的 file URL（见文件头）。`limits` 与安装时校验用同一组（`packages.maxBytes`），
+ * 缺省按包自身大小。名字、sha256 不合法或取到的字节与 sha256 不符时抛错，不落盘。
+ */
+export declare function syncPackage(dir: string, name: string, sha: string, blobs: {
+    get(sha256: string): Promise<Uint8Array>;
+}, limits?: ExtensionPackageLimits): Promise<string>;
+/**
+ * Gets a broken package root out of the way before the rename. Never `rm` in place: another process
+ * on the same volume may have renamed its complete directory in after our `intact` check. The root is
+ * renamed aside atomically and checked again there: if it turns out complete, it is put back (or,
+ * when yet another process filled the root meanwhile, that one is used) and returned; otherwise the
+ * moved-aside copy is deleted. Exported for tests.
+ */
+export declare function clearBrokenRoot(root: string, sha: string): Promise<Marker | undefined>;
+/** `syncPackage` 返回的 entry URL 对应的包根目录（去掉 entry 的各段）。 */
+export declare function packageRootOf(entryUrl: string, entry: string): string;

package/dist/extensions/sync.js

@@ -0,0 +1,242 @@
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { mkdir, readdir, readFile, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve as resolvePath, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { HOST_PROVIDED_PACKAGES, isSafePackagePath, PLUGIN_MANIFEST_FILE, } from "@capybara-hq/plugin-sdk";
+import { LEGACY_FORMAT_MESSAGE, packagePath } from "../packages/tgz.js";
+import { ExtensionPackageError, extractExtensionPackage, } from "./package.js";
+/**
+ * 把内容寻址的插件包同步到本副本的本地目录（C13）：`<dir>/<name>/<sha256 前 16 位>/`。
+ *
+ * - 目录里有校验文件 {@link MARKER} 且其中每个文件的 sha256 都对得上 → 直接复用（同一 sha 重启不再下载）；
+ * - 否则取包（`blobs.get` 按记录的存放位置读取并校验 sha256），先解到同级的临时目录、写好宿主包链接与校验文件，
+ *   再改名换入；目标位置的残缺目录先原子地改名移开再删（不原地删除，见 {@link clearBrokenRoot}）。并发的同机进程
+ *   各自解到自己的临时目录，改名失败时以已就位且完整的为准。
+ * - `node_modules/` 下为 {@link HOST_PROVIDED_PACKAGES} 建指向宿主副本的符号链接：插件 import 的 SDK 与 zod
+ *   就是内核用的那一份（同一模块实例）。插件目录不在宿主 `node_modules` 的上游，别的包一概解析不到。
+ */
+/** 从包存储取到的字节与安装记录的 sha256 不符。 */
+export class PackageShaMismatchError extends Error {
+    constructor(name, sha) {
+        super(`package ${name}: downloaded bytes do not match sha256 ${sha}`);
+        this.name = "PackageShaMismatchError";
+    }
+}
+/** 解包完成后写入包根的校验文件（`wx` 写入：包里自带同名文件时同步失败）。 */
+export const MARKER = ".capybara-package.json";
+/** 插件名规则同清单（`defineExtension` 的 name 校验），用作目录名。 */
+const EXTENSION_NAME_RE = /^[a-z][a-z0-9-]{1,40}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+/** 从内核所在位置向上找 `node_modules/<pkg>`（与 Node 的解析路径一致，不看 exports / 条件），返回真实路径。 */
+function hostPackageDir(pkg) {
+    let d = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(d, "node_modules", ...pkg.split("/"));
+        if (existsSync(join(candidate, "package.json")))
+            return realpathSync(candidate);
+        const up = dirname(d);
+        if (up === d)
+            throw new Error(`cannot find the host copy of ${pkg}`);
+        d = up;
+    }
+}
+let hostDirs;
+/** 宿主提供的包 → 宿主副本目录（首次调用时解析；进程内只读）。 */
+function hostPackageDirs() {
+    hostDirs ??= new Map(HOST_PROVIDED_PACKAGES.map((p) => [p, hostPackageDir(p)]));
+    return hostDirs;
+}
+/** 已就位的目录是否完整：校验文件的 sha256 对得上、每个文件内容对得上、宿主包链接都在。 */
+async function intact(root, sha) {
+    let marker;
+    try {
+        marker = JSON.parse(await readFile(join(root, MARKER), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (marker.sha256 !== sha || typeof marker.files !== "object" || !marker.files)
+        return undefined;
+    if (typeof marker.entry !== "string" || !Object.hasOwn(marker.files, marker.entry))
+        return undefined;
+    for (const [path, digest] of Object.entries(marker.files)) {
+        if (!isSafePackagePath(path))
+            return undefined;
+        try {
+            if (sha256(await readFile(join(root, path))) !== digest)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    for (const pkg of HOST_PROVIDED_PACKAGES) {
+        if (!existsSync(join(root, "node_modules", ...pkg.split("/"), "package.json")))
+            return undefined;
+    }
+    // 文件集合也要一致：多出来的文件（不在校验文件里）同样视为不完整，重新解包
+    let present;
+    try {
+        present = (await listFiles(root)).filter((f) => f !== MARKER);
+    }
+    catch {
+        return undefined;
+    }
+    const expected = Object.keys(marker.files);
+    if (present.length !== expected.length || present.some((f) => !Object.hasOwn(marker.files, f))) {
+        return undefined;
+    }
+    return marker;
+}
+/** 列出目录下的全部普通文件（相对路径，`/` 分隔；不跟随符号链接，宿主包链接不算）。 */
+async function listFiles(root, sub = "") {
+    const out = [];
+    for (const e of await readdir(join(root, sub), { withFileTypes: true })) {
+        const rel = sub === "" ? e.name : `${sub}/${e.name}`;
+        if (e.isDirectory())
+            out.push(...(await listFiles(root, rel)));
+        else if (e.isFile())
+            out.push(rel);
+    }
+    return out;
+}
+/**
+ * 同步一个包到本地并返回 entry 的 file URL（见文件头）。`limits` 与安装时校验用同一组（`packages.maxBytes`），
+ * 缺省按包自身大小。名字、sha256 不合法或取到的字节与 sha256 不符时抛错，不落盘。
+ */
+export async function syncPackage(dir, name, sha, blobs, limits) {
+    if (!EXTENSION_NAME_RE.test(name))
+        throw new Error(`invalid plugin name "${name}"`);
+    if (!SHA256_RE.test(sha))
+        throw new Error(`invalid package sha256 "${sha}"`);
+    const base = join(resolvePath(dir), name);
+    const root = join(base, sha.slice(0, 16));
+    const urlOf = (m) => pathToFileURL(join(root, ...m.entry.split("/"))).href;
+    const existing = await intact(root, sha);
+    if (existing) {
+        // a directory synced before 0.1.0 is complete but in the old format: refuse it the same way
+        await extensionEntryOf(root, name);
+        return urlOf(existing);
+    }
+    const bytes = await blobs.get(sha);
+    if (sha256(bytes) !== sha)
+        throw new PackageShaMismatchError(name, sha);
+    await mkdir(base, { recursive: true, mode: 0o755 });
+    const tmp = join(base, `.tmp-${sha.slice(0, 16)}-${randomBytes(4).toString("hex")}`);
+    try {
+        await extractExtensionPackage(bytes, tmp, limits ?? { maxBytes: bytes.byteLength });
+        const entry = await extensionEntryOf(tmp, name);
+        const files = {};
+        for (const f of await listFiles(tmp))
+            files[f] = sha256(await readFile(join(tmp, f)));
+        if (!Object.hasOwn(files, entry))
+            throw new Error(`package ${name}: entry ${entry} not found`);
+        for (const [pkgName, target] of hostPackageDirs()) {
+            const link = join(tmp, "node_modules", ...pkgName.split("/"));
+            await mkdir(dirname(link), { recursive: true, mode: 0o755 });
+            await symlink(target, link, "dir");
+        }
+        const marker = { sha256: sha, entry, files };
+        await writeFile(join(tmp, MARKER), JSON.stringify(marker), { flag: "wx", mode: 0o644 });
+        // 换入：解包期间同机另一个进程可能已换入完整的目录——以它为准，不删；否则先移走残缺目录
+        const done = await intact(root, sha);
+        if (done)
+            return urlOf(done);
+        const restored = await clearBrokenRoot(root, sha);
+        if (restored)
+            return urlOf(restored);
+        try {
+            await rename(tmp, root);
+        }
+        catch (e) {
+            // 同机另一个进程刚换入：以它为准（必须完整），否则抛原错误
+            const other = await intact(root, sha);
+            if (!other)
+                throw e;
+            return urlOf(other);
+        }
+        return urlOf(marker);
+    }
+    finally {
+        await rm(tmp, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/**
+ * The extension entry (relative to the package root) from the unpacked package's
+ * `.capybara-plugin/plugin.json`. A package in the pre-0.1.0 format (no plugin.json, a `capybara`
+ * section or `app.yaml`) -> {@link ExtensionPackageError} `extension.legacy_format` (the host
+ * records it as the replica's failure instead of loading).
+ */
+async function extensionEntryOf(root, name) {
+    const read = async (path) => {
+        try {
+            return JSON.parse(await readFile(join(root, ...path.split("/")), "utf8"));
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return undefined;
+            throw e;
+        }
+    };
+    const manifest = (await read(PLUGIN_MANIFEST_FILE));
+    if (manifest === undefined) {
+        const pkg = (await read("package.json"));
+        if (pkg?.capybara !== undefined || existsSync(join(root, "app.yaml"))) {
+            throw new ExtensionPackageError([`Package of extension ${name} ${LEGACY_FORMAT_MESSAGE}`], "extension.legacy_format");
+        }
+        throw new Error(`package ${name}: ${PLUGIN_MANIFEST_FILE} is missing`);
+    }
+    const entry = manifest.extension?.entry;
+    if (typeof entry !== "string" || !isSafePackagePath(packagePath(entry))) {
+        throw new Error(`package ${name}: ${PLUGIN_MANIFEST_FILE} has no extension entry`);
+    }
+    return packagePath(entry);
+}
+/**
+ * Gets a broken package root out of the way before the rename. Never `rm` in place: another process
+ * on the same volume may have renamed its complete directory in after our `intact` check. The root is
+ * renamed aside atomically and checked again there: if it turns out complete, it is put back (or,
+ * when yet another process filled the root meanwhile, that one is used) and returned; otherwise the
+ * moved-aside copy is deleted. Exported for tests.
+ */
+export async function clearBrokenRoot(root, sha) {
+    if (!(await exists(root)))
+        return undefined;
+    const aside = join(dirname(root), `.old-${sha.slice(0, 16)}-${randomBytes(4).toString("hex")}`);
+    try {
+        await rename(root, aside);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+    try {
+        const moved = await intact(aside, sha);
+        if (!moved)
+            return undefined;
+        try {
+            await rename(aside, root);
+            return moved;
+        }
+        catch {
+            return await intact(root, sha);
+        }
+    }
+    finally {
+        await rm(aside, { recursive: true, force: true }).catch(() => { });
+    }
+}
+const exists = async (p) => stat(p).then(() => true, () => false);
+/** `syncPackage` 返回的 entry URL 对应的包根目录（去掉 entry 的各段）。 */
+export function packageRootOf(entryUrl, entry) {
+    const file = fileURLToPath(entryUrl);
+    const root = resolvePath(file, ...entry.split("/").map(() => ".."));
+    const rel = relative(root, file);
+    if (rel.startsWith("..") || rel.split(sep).join("/") !== entry) {
+        throw new Error(`entry ${entry} is not inside ${root}`);
+    }
+    return root;
+}

package/dist/files/previewers.controller.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { OrgPreviewerItem, PreviewerItem, PreviewerRegistry } from "./previewers.js";
+declare const PreviewQuery: z.ZodObject<{
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+declare const OrderBody: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        plugin: z.ZodString;
+        id: z.ZodString;
+        disabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * `file-preview@1` (UI refresh B Task 11):
+ * - `GET /api/v1/orgs/:orgId/conversations/:id/files/:fileId/previewers` → `{ previewers }`: the
+ *   extension previewers that take this file version, in the org's order (viewer must read the
+ *   conversation, otherwise 404);
+ * - `GET .../files/:fileId/previews/:plugin/:previewerId?locale=` → `{ view }`: a view previewer's
+ *   render (10 s → 504 `ui.timeout`, throws → 502 `ui.render_failed`, invalid → 502
+ *   `ui.invalid_view`); an embed previewer gets its token from the ui embed-token route with
+ *   `{ conversationId, fileId }` and the file over the message bridge;
+ * - `GET / PUT /api/v1/orgs/:orgId/file-previewers` (`org.extensions.manage`) → `{ items }`: the
+ *   org's order; PUT lists `{ plugin, id, disabled }` first-to-last, the rest follow.
+ */
+export declare class FilePreviewersController {
+    private readonly previewers;
+    constructor(previewers: PreviewerRegistry);
+    forFile(principal: Principal, org: OrgContext, id: string, fileId: string): Promise<{
+        previewers: PreviewerItem[];
+    }>;
+    preview(principal: Principal, org: OrgContext, id: string, fileId: string, plugin: string, previewerId: string, q: z.infer<typeof PreviewQuery>): Promise<{
+        view: import("@capybara-hq/plugin-sdk").UiView;
+    }>;
+    list(org: OrgContext): Promise<{
+        items: OrgPreviewerItem[];
+    }>;
+    put(org: OrgContext, principal: Principal, body: z.infer<typeof OrderBody>): Promise<{
+        items: OrgPreviewerItem[];
+    }>;
+}
+export {};

package/dist/files/previewers.controller.js

@@ -0,0 +1,105 @@
+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 { Body, Controller, Get, Header, Inject, Param, Put, Query } from "@nestjs/common";
+import { z } from "zod";
+import { FILE_PREVIEWERS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+const Id = z.string().min(1).max(100);
+const PreviewQuery = z.object({ locale: z.enum(["zh", "en"]).default("en") });
+const OrderBody = z.object({
+    items: z.array(z.object({ plugin: Id, id: Id, disabled: z.boolean().default(false) })).max(500),
+});
+/**
+ * `file-preview@1` (UI refresh B Task 11):
+ * - `GET /api/v1/orgs/:orgId/conversations/:id/files/:fileId/previewers` → `{ previewers }`: the
+ *   extension previewers that take this file version, in the org's order (viewer must read the
+ *   conversation, otherwise 404);
+ * - `GET .../files/:fileId/previews/:plugin/:previewerId?locale=` → `{ view }`: a view previewer's
+ *   render (10 s → 504 `ui.timeout`, throws → 502 `ui.render_failed`, invalid → 502
+ *   `ui.invalid_view`); an embed previewer gets its token from the ui embed-token route with
+ *   `{ conversationId, fileId }` and the file over the message bridge;
+ * - `GET / PUT /api/v1/orgs/:orgId/file-previewers` (`org.extensions.manage`) → `{ items }`: the
+ *   org's order; PUT lists `{ plugin, id, disabled }` first-to-last, the rest follow.
+ */
+let FilePreviewersController = class FilePreviewersController {
+    previewers;
+    constructor(previewers) {
+        this.previewers = previewers;
+    }
+    async forFile(principal, org, id, fileId) {
+        const p = requireUser(principal);
+        return { previewers: await this.previewers.forFile(org.orgId, id, p.account.id, fileId) };
+    }
+    async preview(principal, org, id, fileId, plugin, previewerId, q) {
+        const p = requireUser(principal);
+        const view = await this.previewers.render({
+            orgId: org.orgId,
+            accountId: p.account.id,
+            conversationId: id,
+            fileId,
+            plugin,
+            id: previewerId,
+            locale: q.locale,
+        });
+        return { view };
+    }
+    async list(org) {
+        return { items: await this.previewers.list(org.orgId) };
+    }
+    async put(org, principal, body) {
+        const actor = principal.kind === "service"
+            ? { tokenId: principal.tokenId }
+            : {
+                accountId: principal.account.id,
+                ...(principal.via === "pat" && { tokenId: principal.tokenId }),
+            };
+        return { items: await this.previewers.put(org.orgId, body.items, actor) };
+    }
+};
+__decorate([
+    Get("conversations/:id/files/:fileId/previewers"),
+    Header("cache-control", "private, no-store"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Param("fileId"))
+], FilePreviewersController.prototype, "forFile", null);
+__decorate([
+    Get("conversations/:id/files/:fileId/previews/:plugin/:previewerId"),
+    Header("cache-control", "private, no-store"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Param("fileId")),
+    __param(4, Param("plugin", new ZodPipe(Id))),
+    __param(5, Param("previewerId", new ZodPipe(Id))),
+    __param(6, Query(new ZodPipe(PreviewQuery)))
+], FilePreviewersController.prototype, "preview", null);
+__decorate([
+    Get("file-previewers"),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentOrg())
+], FilePreviewersController.prototype, "list", null);
+__decorate([
+    Put("file-previewers"),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentOrg()),
+    __param(1, CurrentPrincipal()),
+    __param(2, Body(new ZodPipe(OrderBody)))
+], FilePreviewersController.prototype, "put", null);
+FilePreviewersController = __decorate([
+    Controller("api/v1/orgs/:orgId"),
+    __param(0, Inject(FILE_PREVIEWERS))
+], FilePreviewersController);
+export { FilePreviewersController };