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

package/dist/ui/registry.js

@@ -0,0 +1,90 @@
+import { roleAtLeast } from "../orgs/roles.js";
+/** 会话 id 的格式（UUID）。 */
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** 组织页面（`place: "page"`）所需的最低角色（A38）：guest 只用对话位置的贡献。 */
+export const PAGE_MIN_ROLE = "member";
+/** Places on the conversation page (everything but an org page): they need a `conversationId`. */
+export const isConversationPlace = (place) => place !== "page";
+/** 该角色能否使用这个位置的贡献。 */
+export const canUsePlace = (place, role) => place !== "page" || roleAtLeast(role, PAGE_MIN_ROLE);
+/**
+ * 组织级界面刷新的内核 bus 主题（命名空间 `kernel`）：`org-ui.<orgId>`。
+ * 对话视图的刷新走会话主题 `conv.<id>`（与事件、增量共用），见 `conversationTopic`。
+ */
+export const orgUiTopic = (orgId) => `org-ui.${orgId}`;
+/** 是否为界面刷新消息（bus 上的消息来自其他副本，按形状核对）。 */
+export function isUiBusMessage(m) {
+    if (typeof m !== "object" || m === null)
+        return false;
+    const x = m;
+    return x.kind === "ui" && typeof x.plugin === "string" && typeof x.contribution === "string";
+}
+/** SSE 帧 `event: ui`，数据 `{ plugin, contribution }`。 */
+export const uiFrame = (m) => `event: ui\ndata: ${JSON.stringify({ plugin: m.plugin, contribution: m.contribution })}\n\n`;
+/**
+ * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
+ * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
+ * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ */
+export class PluginUiRegistration {
+    manifest;
+    deny;
+    views = new Map();
+    actions = new Map();
+    declaredViews;
+    contributions;
+    sealed = false;
+    constructor(manifest, 
+    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    deny) {
+        this.manifest = manifest;
+        this.deny = deny;
+        this.declaredViews = new Set(manifest.permissions?.ui?.views ?? []);
+        this.contributions = new Set((manifest.ui ?? []).map((c) => c.id));
+    }
+    /** setup 结束后调用：此后 view / action 抛错。 */
+    seal() {
+        this.sealed = true;
+    }
+    view(id, render) {
+        this.register("view", this.views, id, render);
+    }
+    action(id, handler) {
+        this.register("action", this.actions, id, handler);
+    }
+    /** 校验 invalidate 的目标，返回规范化后的 `{ orgId, conversationId?, contribution }`。 */
+    target(t) {
+        const name = this.manifest.name;
+        const x = (typeof t === "object" && t !== null ? t : {});
+        const id = (v) => typeof v === "string" && v !== "" && v.length <= 200;
+        if (!id(x.orgId))
+            throw new Error(`plugin ${name}: ui.invalidate needs a non-empty orgId`);
+        if (x.conversationId !== undefined &&
+            (typeof x.conversationId !== "string" || !UUID_RE.test(x.conversationId))) {
+            throw new Error(`plugin ${name}: ui.invalidate conversationId must be a UUID`);
+        }
+        if (typeof x.contribution !== "string" || !this.contributions.has(x.contribution)) {
+            throw new Error(`plugin ${name}: ui.invalidate: ${JSON.stringify(x.contribution)} is not a ui contribution in the manifest`);
+        }
+        return {
+            orgId: x.orgId,
+            ...(x.conversationId !== undefined && { conversationId: x.conversationId }),
+            contribution: x.contribution,
+        };
+    }
+    register(what, map, id, fn) {
+        const name = this.manifest.name;
+        if (this.sealed) {
+            throw new Error(`plugin ${name}: ui.${what} is only allowed during setup; setup has completed`);
+        }
+        if (typeof id !== "string" || !this.declaredViews.has(id)) {
+            this.deny(`permissions.ui.views ${String(id)}`);
+        }
+        if (typeof fn !== "function") {
+            throw new Error(`plugin ${name}: ui.${what} "${id}" handler must be a function`);
+        }
+        if (map.has(id))
+            throw new Error(`plugin ${name}: duplicate ui.${what} "${id}"`);
+        map.set(id, fn);
+    }
+}

package/dist/ui/ui-stream.d.ts

@@ -0,0 +1,37 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { CredentialCheck } from "../identity/credential-check.js";
+import { type OrgRole } from "../orgs/roles.js";
+import type { SseOutput, StreamBus, StreamHandle } from "../runtime/stream.js";
+export interface OrgUiStreamsDeps {
+    bus: StreamBus;
+    /**
+     * 调用者此刻的组织角色（组织未删除、账号 active、仍有成员关系，否则 undefined）：
+     * 连接建立时与每 `sseRecheckMs` 复核一次；组织级刷新只服务组织页面，要 member 以上（A38）。
+     */
+    memberRole(orgId: string, accountId: string): Promise<OrgRole | undefined>;
+    config: () => KernelConfig;
+    log: Pick<Logger, "warn">;
+}
+export interface OrgUiStreamParams {
+    orgId: string;
+    viewerAccountId: string;
+    credential: CredentialCheck;
+}
+/** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
+export declare function orgMembership(db: KernelDb): OrgUiStreamsDeps["memberRole"];
+/**
+ * 组织级界面刷新流（SSE）：订阅内核主题 `org-ui.<orgId>`，把插件 `ctx.ui.invalidate`（不带对话）的刷新
+ * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
+ * （订阅、心跳与复核定时器），停机时一并关闭。
+ */
+export declare class OrgUiStreams {
+    private readonly d;
+    private readonly active;
+    constructor(d: OrgUiStreamsDeps);
+    /** 复核凭据与成员关系并订阅；失败时尚未写响应，调用方按普通错误返回。 */
+    open(p: OrgUiStreamParams, out: SseOutput): Promise<StreamHandle>;
+    closeAll(): void;
+    get size(): number;
+}

package/dist/ui/ui-stream.js

@@ -0,0 +1,162 @@
+import { ApiError } from "../errors.js";
+import { roleAtLeast } from "../orgs/roles.js";
+import { isUiBusMessage, orgUiTopic, PAGE_MIN_ROLE, uiFrame } from "./registry.js";
+/** 组织成员角色（一条查询）：组织未删除、账号 active、仍有成员关系。 */
+export function orgMembership(db) {
+    return async (orgId, accountId) => {
+        const row = await db
+            .selectFrom("memberships")
+            .innerJoin("orgs", "orgs.id", "memberships.org_id")
+            .innerJoin("accounts", "accounts.id", "memberships.account_id")
+            .select("memberships.role")
+            .where("memberships.org_id", "=", orgId)
+            .where("memberships.account_id", "=", accountId)
+            .where("orgs.deleted_at", "is", null)
+            .where("accounts.status", "=", "active")
+            .executeTakeFirst();
+        return row?.role;
+    };
+}
+async function authorize(d, p) {
+    const denied = await p.credential();
+    if (denied !== null)
+        return denied;
+    const role = await d.memberRole(p.orgId, p.viewerAccountId);
+    if (role === undefined)
+        return "org.not_found";
+    return roleAtLeast(role, PAGE_MIN_ROLE) ? null : "ui.not_found";
+}
+/** 慢客户端的积压上限（刷新帧很小，超过即说明客户端不读了）。 */
+const MAX_BACKLOG_BYTES = 1024 * 1024;
+/**
+ * 组织级界面刷新流（SSE）：订阅内核主题 `org-ui.<orgId>`，把插件 `ctx.ui.invalidate`（不带对话）的刷新
+ * 转发为 `event: ui`（`data: {"plugin","contribution"}`）。跨副本只经 Redis bus；进程内只持有连接本身的资源
+ * （订阅、心跳与复核定时器），停机时一并关闭。
+ */
+export class OrgUiStreams {
+    d;
+    active = new Set();
+    constructor(d) {
+        this.d = d;
+    }
+    /** 复核凭据与成员关系并订阅；失败时尚未写响应，调用方按普通错误返回。 */
+    async open(p, out) {
+        const denied = await authorize(this.d, p);
+        if (denied !== null)
+            throw new ApiError(denied, "Access denied");
+        const conn = new OrgUiConnection(this.d, p, out, () => this.active.delete(conn));
+        this.active.add(conn);
+        try {
+            await conn.subscribe();
+        }
+        catch (e) {
+            conn.close();
+            throw e;
+        }
+        return conn;
+    }
+    closeAll() {
+        for (const c of [...this.active])
+            c.close();
+    }
+    get size() {
+        return this.active.size;
+    }
+}
+class OrgUiConnection {
+    d;
+    p;
+    out;
+    onClosed;
+    closed = false;
+    begun = false;
+    rechecking = false;
+    unsubscribe;
+    timers = [];
+    constructor(d, p, out, onClosed) {
+        this.d = d;
+        this.p = p;
+        this.out = out;
+        this.onClosed = onClosed;
+    }
+    async subscribe() {
+        const un = await this.d.bus.subscribe(orgUiTopic(this.p.orgId), (m) => {
+            // begin() 之前（响应头还没写）到达的刷新丢掉：网页连上后会先取一次视图
+            if (this.begun && isUiBusMessage(m))
+                this.write(uiFrame(m));
+        });
+        if (this.closed)
+            await un();
+        else
+            this.unsubscribe = un;
+    }
+    begin() {
+        if (this.closed)
+            return;
+        this.begun = true;
+        const { sseHeartbeatMs, sseRecheckMs } = this.d.config().runtime;
+        this.timers.push(setInterval(() => this.write(": ping\n\n"), sseHeartbeatMs), setInterval(() => void this.recheck(), sseRecheckMs));
+    }
+    close(mode = "end") {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const t of this.timers)
+            clearInterval(t);
+        this.timers = [];
+        const un = this.unsubscribe;
+        this.unsubscribe = undefined;
+        un?.().catch((err) => this.d.log.warn("org ui stream unsubscribe failed", { orgId: this.p.orgId, err }));
+        if (this.begun) {
+            try {
+                if (mode === "abort")
+                    this.out.abort();
+                else
+                    this.out.end();
+            }
+            catch {
+                // 连接已断开
+            }
+        }
+        this.onClosed();
+    }
+    write(chunk) {
+        if (this.closed)
+            return;
+        try {
+            this.out.write(chunk);
+        }
+        catch {
+            this.close("abort");
+            return;
+        }
+        if (this.out.backlog() > MAX_BACKLOG_BYTES) {
+            this.d.log.warn("org ui stream client too slow; closing", { orgId: this.p.orgId });
+            this.close("abort");
+        }
+    }
+    /** 复核凭据与成员关系；失败时发最后一帧 `event: error`（`data: {"code"}`）再关闭。 */
+    async recheck() {
+        if (this.closed || this.rechecking)
+            return;
+        this.rechecking = true;
+        let code;
+        try {
+            code = await authorize(this.d, this.p);
+        }
+        catch (err) {
+            this.d.log.warn("org ui stream access re-check failed; closing", {
+                orgId: this.p.orgId,
+                err,
+            });
+            code = "internal";
+        }
+        finally {
+            this.rechecking = false;
+        }
+        if (code === null || this.closed)
+            return;
+        this.write(`event: error\ndata: ${JSON.stringify({ code })}\n\n`);
+        this.close();
+    }
+}

package/dist/ui/views.controller.d.ts

@@ -0,0 +1,81 @@
+import { type UiActionResult, type UiView } from "@capybara-hq/plugin-sdk";
+import { type OnModuleDestroy } from "@nestjs/common";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import type { ApiTokenService } from "../identity/api-tokens.js";
+import { type Principal } from "../identity/principal.js";
+import type { SessionService } from "../identity/sessions.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type EmbedTokens } from "./embed-token.js";
+import type { OrgUiStreams } from "./ui-stream.js";
+import type { UiContributionItem, UiViews } from "./views.js";
+declare const ViewQuery: z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+    item: z.ZodOptional<z.ZodString>;
+    callId: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ActionBody: z.ZodObject<{
+    actionId: z.ZodString;
+    payload: z.ZodOptional<z.ZodUnknown>;
+    answer: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+    conversationId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strip>;
+declare const EmbedTokenBody: z.ZodDefault<z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strip>>;
+/**
+ * 插件界面（第一档：渲染 schema；第二档：嵌入应用），会话鉴权、`ui.use`（只给人用，服务令牌 403）：
+ * - `GET  /api/v1/orgs/:orgId/ui/contributions` → `{ items: { plugin, id, title, place, legacyPlace?, kind, path?, icon }[] }`
+ *   (place normalized: the old `conversation` is `panel` with `legacyPlace`; aliases and file-preview
+ *   embeds are not listed)
+ *   （`path` 仅 embed）；
+ * - `GET  /api/v1/orgs/:orgId/ui/views/:plugin/:id?conversationId=&locale=&item=&callId=&key=` → `{ view }`
+ *   （`item`: the panel item to scroll to; `callId` / `key`: an inline card's tool call）；
+ * - `POST /api/v1/orgs/:orgId/ui/actions/:plugin/:id`（`{ actionId, payload?, answer?, conversationId?, locale? }`）
+ *   → `{ toast }` | `{ view }`；
+ * - `GET  /api/v1/orgs/:orgId/ui/stream`：组织级刷新 SSE（`event: ui`，`data: {"plugin","contribution"}`）；
+ * - `POST /api/v1/orgs/:orgId/ui/embeds/:plugin/:id/token`（`{ conversationId? }`）
+ *   → `{ token, src: "/plugin-ui/<plugin>/<path 去掉 /ui/>", expiresAt, expiresIn }`：嵌入令牌
+ *   （300 秒，`expiresIn` 为秒数，见 `embed-token.ts`）。
+ *   插件须在组织启用、贡献须是 embed；对话嵌入要求能访问该对话（否则 404）。令牌只给插件路由用，
+ *   内核鉴权守卫不认它（它不是 API 令牌）。
+ * 对话视图的刷新走现有的会话流 `/conversations/:id/stream`。
+ * 角色（A38）：组织页面（`place: "page"`，含组织级刷新流）只给 member 以上，guest 一律 404 `ui.not_found`、
+ * 列表里也不出现；对话位置的贡献给能访问该对话的任何成员。插件收到的 `role` 来自 OrgGuard 查出的成员关系。
+ */
+export declare class UiController implements OnModuleDestroy {
+    private readonly views;
+    private readonly streams;
+    private readonly sessions;
+    private readonly tokens;
+    private readonly embeds;
+    constructor(views: UiViews, streams: OrgUiStreams, sessions: SessionService, tokens: ApiTokenService, embeds: EmbedTokens);
+    contributions(principal: Principal, org: OrgContext): Promise<{
+        items: UiContributionItem[];
+    }>;
+    view(principal: Principal, org: OrgContext, plugin: string, id: string, q: z.infer<typeof ViewQuery>): Promise<{
+        view: UiView;
+    }>;
+    action(principal: Principal, org: OrgContext, plugin: string, id: string, body: z.infer<typeof ActionBody>): Promise<UiActionResult>;
+    embedToken(principal: Principal, org: OrgContext, plugin: string, id: string, body: z.infer<typeof EmbedTokenBody>): Promise<{
+        token: string;
+        src: string;
+        expiresAt: string;
+        expiresIn: number;
+    }>;
+    /** 组织级刷新流：与会话流一样用 `reply.hijack()` 直接写原始响应；心跳与复核间隔同 `runtime.sse*`。 */
+    stream(principal: Principal, org: OrgContext, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    /** 停机：关闭本进程的全部组织刷新流。 */
+    onModuleDestroy(): void;
+}
+export {};

package/dist/ui/views.controller.js

@@ -0,0 +1,261 @@
+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 { UI_LIMITS } from "@capybara-hq/plugin-sdk";
+import { Body, Controller, Get, HttpCode, Inject, Param, Post, Query, Req, Res, } from "@nestjs/common";
+import { z } from "zod";
+import { API_TOKENS, EMBED_TOKENS, ORG_UI_STREAMS, SESSIONS, UI_VIEWS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { credentialCheck } from "../identity/credential-check.js";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { EMBED_TOKEN_TTL_SECONDS } from "./embed-token.js";
+const BEARER_RE = /^Bearer\s+(\S+)$/i;
+const Locale = z.enum(["zh", "en"]).default("en");
+const Id = z.string().min(1).max(100);
+const ViewQuery = z
+    .object({
+    conversationId: z.string().min(1).max(100).optional(),
+    locale: Locale,
+    /** A panel opened from an open target: the item to scroll to. */
+    item: z.string().min(1).max(200).optional(),
+    /** An inline card: the tool call it hangs off, and its `ToolResult.card.key`. */
+    callId: z.string().min(1).max(200).optional(),
+    key: z.string().min(1).max(200).optional(),
+})
+    .refine((q) => q.key === undefined || q.callId !== undefined, {
+    message: "key needs callId",
+});
+/**
+ * 表单答案（plugin-sdk 的 `FormAnswer`）。SDK 的 InputForm 没有单独的字段数 / 选项数上限，
+ * 这里沿用视图的上限：键数与多选数组长度 ≤ `UI_LIMITS.tableRows`，单个文本 ≤ `UI_LIMITS.textChars`。
+ */
+const AnswerText = z.string().max(UI_LIMITS.textChars);
+const FormAnswerSchema = z
+    .record(z.string().max(100), z.union([AnswerText, z.number(), z.boolean(), z.array(AnswerText).max(UI_LIMITS.tableRows)]))
+    .refine((a) => Object.keys(a).length <= UI_LIMITS.tableRows, {
+    message: `answer must have at most ${UI_LIMITS.tableRows} fields`,
+});
+/** 按钮 payload 的 JSON 序列化后 UTF-8 字节数（与 `validateUiView` 对按钮 payload 的上限一致）。 */
+const payloadBytes = (v) => Buffer.byteLength(JSON.stringify(v) ?? "", "utf8");
+const ActionBody = z.object({
+    actionId: z.string().min(1).max(200),
+    payload: z
+        .unknown()
+        .optional()
+        .refine((v) => v === undefined || payloadBytes(v) <= UI_LIMITS.payloadBytes, {
+        message: `payload must be at most ${UI_LIMITS.payloadBytes} bytes as JSON`,
+    }),
+    answer: FormAnswerSchema.optional(),
+    conversationId: z.string().min(1).max(100).optional(),
+    locale: Locale,
+});
+const EmbedTokenBody = z
+    .object({
+    conversationId: z.string().min(1).max(100).optional(),
+    /** Only a `file-preview` embed: the file version it previews. */
+    fileId: z.uuid().optional(),
+})
+    .default({});
+/** 嵌入页的同源代理前缀（网页 `/plugin-ui/<plugin>/<rest>` → 内核 `/plugins/<plugin>/ui/<rest>`）。 */
+const embedSrc = (plugin, path) => `/plugin-ui/${plugin}/${path.replace(/^\/ui\//, "")}`;
+/**
+ * 插件界面（第一档：渲染 schema；第二档：嵌入应用），会话鉴权、`ui.use`（只给人用，服务令牌 403）：
+ * - `GET  /api/v1/orgs/:orgId/ui/contributions` → `{ items: { plugin, id, title, place, legacyPlace?, kind, path?, icon }[] }`
+ *   (place normalized: the old `conversation` is `panel` with `legacyPlace`; aliases and file-preview
+ *   embeds are not listed)
+ *   （`path` 仅 embed）；
+ * - `GET  /api/v1/orgs/:orgId/ui/views/:plugin/:id?conversationId=&locale=&item=&callId=&key=` → `{ view }`
+ *   （`item`: the panel item to scroll to; `callId` / `key`: an inline card's tool call）；
+ * - `POST /api/v1/orgs/:orgId/ui/actions/:plugin/:id`（`{ actionId, payload?, answer?, conversationId?, locale? }`）
+ *   → `{ toast }` | `{ view }`；
+ * - `GET  /api/v1/orgs/:orgId/ui/stream`：组织级刷新 SSE（`event: ui`，`data: {"plugin","contribution"}`）；
+ * - `POST /api/v1/orgs/:orgId/ui/embeds/:plugin/:id/token`（`{ conversationId? }`）
+ *   → `{ token, src: "/plugin-ui/<plugin>/<path 去掉 /ui/>", expiresAt, expiresIn }`：嵌入令牌
+ *   （300 秒，`expiresIn` 为秒数，见 `embed-token.ts`）。
+ *   插件须在组织启用、贡献须是 embed；对话嵌入要求能访问该对话（否则 404）。令牌只给插件路由用，
+ *   内核鉴权守卫不认它（它不是 API 令牌）。
+ * 对话视图的刷新走现有的会话流 `/conversations/:id/stream`。
+ * 角色（A38）：组织页面（`place: "page"`，含组织级刷新流）只给 member 以上，guest 一律 404 `ui.not_found`、
+ * 列表里也不出现；对话位置的贡献给能访问该对话的任何成员。插件收到的 `role` 来自 OrgGuard 查出的成员关系。
+ */
+let UiController = class UiController {
+    views;
+    streams;
+    sessions;
+    tokens;
+    embeds;
+    constructor(views, streams, sessions, tokens, embeds) {
+        this.views = views;
+        this.streams = streams;
+        this.sessions = sessions;
+        this.tokens = tokens;
+        this.embeds = embeds;
+    }
+    async contributions(principal, org) {
+        requireUser(principal);
+        return { items: await this.views.contributions(org.orgId, org.role) };
+    }
+    async view(principal, org, plugin, id, q) {
+        const p = requireUser(principal);
+        const view = await this.views.render({
+            orgId: org.orgId,
+            accountId: p.account.id,
+            role: org.role,
+            plugin,
+            id,
+            ...(q.conversationId !== undefined && { conversationId: q.conversationId }),
+            locale: q.locale,
+            ...(q.item !== undefined && { item: q.item }),
+            ...(q.callId !== undefined && {
+                card: { callId: q.callId, ...(q.key !== undefined && { key: q.key }) },
+            }),
+        });
+        return { view };
+    }
+    async action(principal, org, plugin, id, body) {
+        const p = requireUser(principal);
+        return this.views.act({
+            orgId: org.orgId,
+            accountId: p.account.id,
+            role: org.role,
+            plugin,
+            id,
+            ...(body.conversationId !== undefined && { conversationId: body.conversationId }),
+            locale: body.locale,
+        }, {
+            actionId: body.actionId,
+            ...(body.payload !== undefined && { payload: body.payload }),
+            ...(body.answer !== undefined && { answer: body.answer }),
+        });
+    }
+    async embedToken(principal, org, plugin, id, body) {
+        const p = requireUser(principal);
+        const target = await this.views.embed({
+            orgId: org.orgId,
+            accountId: p.account.id,
+            role: org.role,
+            plugin,
+            id,
+            ...(body.conversationId !== undefined && { conversationId: body.conversationId }),
+            ...(body.fileId !== undefined && { fileId: body.fileId }),
+        });
+        const { token, expiresAt } = this.embeds.issue({
+            plugin: target.plugin,
+            orgId: org.orgId,
+            accountId: p.account.id,
+            role: org.role,
+            ...(target.conversationId !== undefined && { conversationId: target.conversationId }),
+            ...(target.fileId !== undefined && { fileId: target.fileId }),
+            contribution: target.contribution,
+        });
+        return {
+            token,
+            src: embedSrc(target.plugin, target.path),
+            expiresAt: expiresAt.toISOString(),
+            // 网页按收到的时刻加上它安排续期，不比较浏览器时钟与 expiresAt
+            expiresIn: EMBED_TOKEN_TTL_SECONDS,
+        };
+    }
+    /** 组织级刷新流：与会话流一样用 `reply.hijack()` 直接写原始响应；心跳与复核间隔同 `runtime.sse*`。 */
+    async stream(principal, org, req, reply) {
+        const p = requireUser(principal);
+        const res = reply.raw;
+        const handle = await this.streams.open({
+            orgId: org.orgId,
+            viewerAccountId: p.account.id,
+            credential: credentialCheck(p, BEARER_RE.exec(req.headers.authorization ?? "")?.[1], {
+                sessions: this.sessions,
+                tokens: this.tokens,
+            }),
+        }, {
+            write: (chunk) => {
+                res.write(chunk);
+            },
+            backlog: () => res.writableLength,
+            end: () => {
+                res.end();
+            },
+            abort: () => {
+                res.destroy();
+            },
+        });
+        reply.hijack();
+        res.on("close", () => handle.close());
+        if (res.destroyed || !res.socket || res.socket.destroyed) {
+            handle.close();
+            res.destroy();
+            return;
+        }
+        res.writeHead(200, {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache",
+            "x-accel-buffering": "no",
+            connection: "keep-alive",
+        });
+        res.flushHeaders();
+        handle.begin();
+    }
+    /** 停机：关闭本进程的全部组织刷新流。 */
+    onModuleDestroy() {
+        this.streams.closeAll();
+    }
+};
+__decorate([
+    Get("contributions"),
+    OrgAction("ui.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], UiController.prototype, "contributions", null);
+__decorate([
+    Get("views/:plugin/:id"),
+    OrgAction("ui.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("plugin", new ZodPipe(Id))),
+    __param(3, Param("id", new ZodPipe(Id))),
+    __param(4, Query(new ZodPipe(ViewQuery)))
+], UiController.prototype, "view", null);
+__decorate([
+    Post("actions/:plugin/:id"),
+    HttpCode(200),
+    OrgAction("ui.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("plugin", new ZodPipe(Id))),
+    __param(3, Param("id", new ZodPipe(Id))),
+    __param(4, Body(new ZodPipe(ActionBody)))
+], UiController.prototype, "action", null);
+__decorate([
+    Post("embeds/:plugin/:id/token"),
+    HttpCode(200),
+    OrgAction("ui.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("plugin", new ZodPipe(Id))),
+    __param(3, Param("id", new ZodPipe(Id))),
+    __param(4, Body(new ZodPipe(EmbedTokenBody)))
+], UiController.prototype, "embedToken", null);
+__decorate([
+    Get("stream"),
+    OrgAction("ui.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Req()),
+    __param(3, Res())
+], UiController.prototype, "stream", null);
+UiController = __decorate([
+    Controller("api/v1/orgs/:orgId/ui"),
+    __param(0, Inject(UI_VIEWS)),
+    __param(1, Inject(ORG_UI_STREAMS)),
+    __param(2, Inject(SESSIONS)),
+    __param(3, Inject(API_TOKENS)),
+    __param(4, Inject(EMBED_TOKENS))
+], UiController);
+export { UiController };